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By Marshall Clow 


Living with a Mac 24/7 


OK - I'll say it. My name ls Marshall, and I cany a 
Macintosh witli me all the time. 

I am not alone doing this. People have been carrying their 
computers for years. An acquaintance of mine started with a Mac 
Portable, He carried it with him everywhere for almost 2 years. (Yes, 
he lias a strong back,) The PowerBook 2400 inspired many people 
to do this; it is very small and very fight, I know a few people who 
have carried their 2400s with diem for several years. 1 carried a 2400 
myself for about 18 months. Recently, my employer bought me a 
Titanium PowerBook, and I switched to that It s a lot bigger than 
the 2400, but it has other advantages. 

Apple’s new iBook is designed to be carried everywhere. 
At less than 5 pounds, it doesn’t weigh you down, and it is small 
enough to fit in a backpack and leave room for plenty of other stuff. 
One of tiie target audiences for die new iBook are students, who, as 
a group, never really have just one place to work 

Apple has always marketed PowerRooks as 'the computer 
that can go anywhere widi you”, but their arguments are more 
compelling when they as PowerRooks get smaller and lighten 
What happens when you have a computer with you all 
the time? As a software developer, these are the things that i 
have noticed: 

* 1 cun work anywhere. This is especially important for people 
who have more dian one job ff you ride a train or a bus to work, 
you can work while you are travelling to and from work. The 
same principle applies if you carpool to work, Last week, 1 had 
to get my car serviced Radier llian worry alx)ut arranging a ride 
after dropping off the car (and back later), I worked for about 
two hours in the repair shop’s waiting room. 

* 1 have all my “working files 11 with me all the time. If 1 want to 
edit a photo that 1 took last week, 1 don’t go to the computer” 
to edit it; I “pull out the computer” and start editing. 

* The computer becomes a part of you. It gradually changes 
from a mass-produced piece of hardware and software to a 
device that is customized to exactly how you want it. These 
changes can lx? small tweaks, like changing the speed of the 
track pad, to installing a Dvorak keyboard, up to large 
hardware modifications. PowerBook 2400 owners are 
notorious for these kind of hardware changes; see 
<http://webobjects.uwaterloD.ca/mac2400/hardware.hrml> for some 
examples. I haven't changed the TiPB much yet. 


* Unlike most computers these days, a 7/24 computer spends 
much of the time not connected to any netw ork. Becau.se of this, 
I keep all my files on my local hard disk, not stored on a file 
server somewhere. For those rimes when 1 am in an office (or at 
home ) an Airport card is a big convenience; when 1 am not in an 
office, a Ricoc het wireless modem works well, 

* Anything that’s not internal to the computer is likely to gel 
left behind. Most of the time, I only bring a power supply 
with me. Many times, 1 leave that at home, too. 1 do carry 
headphones, I hough. 

* Since I can use die computer anywhere, I tend to work in spurts. 

I can pull out the computer anytime 1 have a few minutes to wait. 

* I tend to have several projects active at once, I don't have any 
problem working on one of these projects lor 10-15 minutes at a 
time, whenever inspiration strikes me. 

* I don't have to have the fastest computer around, but it needs to 
have a lot of RAM and disk space. If Code Warrior ain’t compile 
my project Ixxuuse 1 don’t have enough RAM, then J can’t work, 

* Unfortunately, the terms 'portable 1 and large screen’ don’t really 
go together. I miss having dual 20" monitors, hut I can’t carry 
them around with me, 

* Backup strategies require a bit of thought, ft doesn't take many 
hours before the data on the computer is woith significantly more 
than the actual computer. Since die computer can get 
dropped/lost/stolen, 1 back it up regularly. 

* 1 don’t carry a CL) player. 1 keep a selection of MP3’s on my 
computer (see lots of disk space 1 above) and play them when 1 
want music. On an airplane, I watch movies on die computer. 

Is This For Everyone? 

Of course noL 

Many people are quite happy to turn the computer off at the 
end of the workday, and leave it off until the next morning. Some 
people feel more productive if they have an office or desk to work 
at. Other people have trouble working with distinctions, so a quiet 
office is die only place for them. 

On the other hand, l sure enjoy being able to use my 
computer wherever I am; this summer I will be spending lots of 
time working outside in my back yard! Mi 
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POWERPLANT 

WORKSHOP 


By Aaron Montgomery 


Debugging Basics 


How one goes about writing a 
PowerPlant application 

These Articles 

iTils is the second article in a series of articles about 
Metro works’ PowerPlanL application framework. The first 
article provided an introduction to how the framework deals 
with Commands, This article focuses on the debugging classes 
in the framework. This series assumes familiarity with the C++ 
language, the Macintosh Toolbox API and the Code Warrior 
IDE* The articles were written using Code Warrior 6 with the 
net-update to IDE 4,1,0,3 and no other modifications. 

Why Debugging Now? 

There are (at least) three reasons not to do debugging so 
early in this series of articles. First, debugging doesn't 
directly solve the problem of writing the code for the 
application, Second, the debugging classes use a lot of 
advanced PowerPlant concepts. Third, the debugging classes 
are in the Jrt Progress folder and they may change 
dramatically between CodeWarrior releases. However, there 
are (at least) two better reasons to talk about debugging now 
instead of waiting. First, debugging code should be written as 
the program is written instead of retrofitting it to existing 
code. Second, the debugging tools can also be used to learn 
about how the framework operates. In particular, the 
debugging classes in PowerPlant can be used to examine the 
command chain (discussed in the first article) and the visual 
hierarchy (which will be discussed in third article). 

Article Layout 

Instead of following rhe code straight through from start 
to finish, this article is organized by topic. We will quickly 
describe changes to the project and the main() function. Most 
of this can be transplanted from one project to the next 
without modification. Then we will cover the various facets 
of the Debugging Classes. It is probably best to read Lhis 


article at least twice since many times topics will appear in 
the text prior to the point where they are explained. 

Changes To the Project 

Although the project for the first article had both a Debug 
and Final build, there was little to distinguish them from each 
other. When setting up the debug projects you will need to 
include the Debugging Classes (which are included in the 
Advanced stationary option). If you are attempting to add these 
classes to an existing project, you need to I) a little careful. The 
files UDebugging.cp and UDebuggfngPlus.cp implement the same 
functions. You should include II Debuggings in rhe Final builds 
and UDebuggingPlusxp in [lie Debug builds. The resource files 
PF Debug Aterts.rsrc and PP Debug Supporfrsrc also duplicate 
resources, the first should l^e used in the Final builds and die 
second in the Debug builds. I also did the same for the 
LDebugStream class: the header LDebugStream.h has two 
implementations: IDebugStream.cp for Debug builds and 
LFinalStream.cp for Final builds. 

Included with the Advanced stationary is an “Utilities* folder 
with some source code. 1 have renamed the folder to “Ilsofs 
Utilities" since he wrote ihese sources and I haven't changed 
them much. These implement new and delete using some of the 
PowerPlant features, i also added the access path to Hacked Plant, 
where I’ve placed some modified PowerPlant source files. 
Comments about what changed and why are included in these 
files. If you are going to use these changes in all your projects, 
it might be worthwhile using a Source 'free for the Hacked PI ant 
files so that muhipic projects can use them. 

Once the.se changes have been made, the difference between 
these two targets is the setting of two macros and a lot of 
conditional compilation. The macro NDEBUG should only Lie 
defined for the Final target and the macro PP_Debug should be set 
to 1 tor the Debug version and to 0 for the Final version. In order 
to avoid conditional compilation within the main source files, most 
of the headers provide macros dial dqxrnc! on Lhe PP_Debug 
setting, The PowerPlant framework uses macros to avoid cluttering 
your main code with conditional compilation and 1 have added the 


Aaron teaches in die Mathematics Department at Central Washington University in Ellensburg, WA. Outside of hLs job, he spends lime riding his 
mountain bike, watching movies and entertaining his wife and two sons. You can email him at montgoaa@cwij,edu, try to catch his attention in die 
newsgroup comp sysame,ot>p, powerplant or visit Iris web site at mac69Iri8.math.cwu.edu :8080/. 
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requirements, only to feel like you're sacrificing one requirement over another? 

FairCom has delivered uncompromising database technology to commercial developers for 
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CDebuggingUtUities class in order lo remove even more conditionals 
from the main files, As a warning, 1 don’t intend to describe how 
Lhe CDebuggingUtilities methods do what 1 claim they do. The file 
is documented with commentary if you arc curious. 

four support packages can be used with Power Plant's 
debugging classes: MoreFiles, QC t Spotlight and DebitgNew, 
The standard stationary and this article use only DcbugNew 
and none of the others, if you have these (MoreFiles 
<http://members.aolxom/jumpfong/> is free, QC and Spotlight 
<http://w%rw.oityxdechxom/> are commercial), you can include 
their source files and libraries and enable support for them in 
the prefix files. 

Adding Some Bugs 

The first thing I did to the project was to add some bugs. 
This involves creating a menu and adding the code to handle the 
bugs I introduced. The menu can be created in Constructor (the 
resource editor provided for PowerPoint), The steps involved 
with Constructor are no! that different from any either ResEdit or 
Rcsoureerer. To add a menu, you would open the 
AppHesources.ppob file, select the Menus (MENU) item in the 
window and then created a new menu resource (New Menu 
Resource in the Edit menu). Unless you want the menu to be 
titled untitled, you would select the new menu and change its 
name to Bad Things and its ID number to 1000, You could do this 
directly in the AppResouroes,ppob window or you could open an 
Inspector window from the Window menu. In general, if you 
select resource IDs above 999 you won't conflict with any of the 
PowerPlant resources. Now double-click the menu. This will 
open the Menu editing window. You would then add new menu 
items (using New Menu Item in the Edit menu). Next, change the 
menu names and add command numbers using the tab key (or 
an Inspector window). 

Next you would modify the FindCommandStatusO and 
ObeyCommandQ code to indicate that these should be enabled 
and to implement the bugs. This was done in the CDocumentApp 
class and you can view the code to see how extra eases were 
added to the switch statements in these methods. We will discuss 
exactly what the code inside each branch does later in this 
article, suffice it to say these are tilings you typically would not 
want your application to do. 

Code Changes main-cp 

The code changes in the mainQ function are not specific to 
ihis particular PowerPlant application. As a result the axle in this 
project can serve as a template for any other applications you 
write. Due to space considerations, lit only do a quick overview 
of what the axle does here, leaving some topics for later in the 
artic le and others unexplored completely. In the source file, the 
comments from last month's article is indicated by comments 
beginning with //I while the comments which have been 
introduced for this article is indicated by //• 

mainQ in nuiincp 

int. main!) 
i 

(void) set_ne vAland 1 e r ( PP_N ewllaii dl**r ) ; 
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try 

i 

CDebu^Utilities::SetAction(): 

SLR&ee t Eaakis_(): 

DebugNt’wForgGlLeaks_( ] ; 

InitializeHeapC5): 

UQLiGIobals::InitializeToolbox(); 

;;FlushEvents{everyEvent. nil): 

UErivirontaent:: In itEnvi tro nment () ; 

CDebugllt IIities;; Ch&ckEtwirouiaent (] ; 

LGrowZone* theGrowZone = NEW LGrowZone[20000); 
ValidateQbject_(theCrowZone): 
Signallf.CtheGrowZorieDMeinorylsLQwO); 


CDncumenTApp theApp: 
theApp.RunO ; 

1 

CDebygUtilitaes;;FowerFIantCleanUp{); 
DebugNewReportLeaks.O: 

CDebugUtilities::ShovLeakEO: 

I 

catch (...) 

I 

3ignalStringLiteral_("Exception caught in main"); 


return 0; 

The hrsL thing we do is to install our own handler for new. 
This handier is designed to use other classes in the PowerPlant 
framework to handle low memory situations. All the 
C Debug Utilities methods will he In lined no-ops in the Final build, 
we discuss what they will do in the Debug build, SetActionQ will 
establish the behavior of Throw, and Signal _ macros (discussed 
in a Inter section). SLResetLeaks_() and DebugNawForgetLeaks, () 
arc used in debugging memory (discussed in a later section). 
After this we call the standard initialization routines for a 
PowerPoint application, adding a call to CDebugUtiNties' method 
CheekEnvironmentO which confirms that we are nmning on a 
system supporting our Debugging Classes. 

The LGrowZone class is designed to provide an extra 
memory cushion when the system has mn out of ways to 
provide us with memory. You should read the comments at the 
top of the LGrowZono.cp file to take full advantage of the 
LGrowZone object but for this project we ll just set aside 20,000 
bytes of space. The ValidateObjecC is a memory debugging 
macro and the call to Signal will raise a Signal, if we could not 
create the cushion for some reason. 

The placement of the CDocumontApp inside its own scope 
insures that it will be obstructed prior to checking for memory 
leaks. A number of PowerPlant objects are usually not destructed 
until application termination, bur they will show up as leaks while 
you are debugging. Hie PowerPlantCleanUp() mcihtxl will delete all 
of the.se objects so that you do not have any phantom leaks 
showing up In your log files. Finally DebugMowReportLeaks.O will 
write any leaks found to a log Hie and ShowLeaks() will open that 
log file in CodeWarrior if any leaks were found (die code for 


ShowLeaksQ was posted in the PowerPlant newsgroup by David 
Phillip Oster). 

CDocitmfntApp Changes 

There arc a few stock changes to the CDocumentApp classes 
that need to be made. Again, like the changes in the function 
mainQ, I won t describe how they do what 1 say they do but you 
can read the documentation in the source file's commentary. 

CDocumtrntAppO in CDocumentApp.cp 

CDocumentApp;:CDocumentApp{) 

{ 

if (UEnvirontnent::HasFeature(env.HasAppearance)) [ 
t : He g, j s te r Appear an ceCl lent t) i 

J 

CDebugUtillties::AddSI0UXAttacbment(this)i 
UControlfteftietry;:Regi^terClasses(); 

CTextDocument::RegisterClasses{); 


We will attach two attachments to the CDocumentApp 
object in order to aid our debugging. Attachments intercept the 
ObeyCommand() method and are able to extend the number of 
commands a LCommander is able to handle. This ability to 
extend any LCommanders list of commands without changing 
the LCommander's source code is a powerful technique for 
code reuse and you should read the more complete discussion 
of attachments in Chapter 15 of The PowerPlant Book or in 
the March 1999 MacTech article by John C. Daub. 

The LSIOUX Attach men! allows us to use a console 
window for the streams cout and cerr. Although 1 have found 
that it sometimes interferes with the program, you may find 
it useful and so I have given an example of its use here. This 
should only be used in the Debug builds and so 1 created a 
CDebugUtilities method to be called in the CDocumentApp's 
constructor to handle the conditional compilation. 

The other new code here is a call to 
UControIRegistry;;FlegisterClasses(), This call is needed to 
prepare for the dialogs Lhat the debugging classes will use. 
We will discuss this need for registering classes in the next 
article. The other place an attachment is added is in the 
Initialize^ method. 

InitializeO in CDoaimentApp.cp 

void 

CDocumentApp:: Initialize() 

I 

LDocApplication?:Initialize0 - 

CDebugUtilities : ^AddDebugMenuAtTacbnentfthis); 

I 

The first thing to be done is to call lnitialize() for the base 
class of CDocumentApp. This should always be your first call 
in your lnitialize{) methods. The LDebugMenuAttachment 
provides the menu interface to the debugging classes. Since 
it must be attached after the menu bar has been initialized, it 
needs to be added in the CDocumentApp's lnitialize() method 
(not the constructor). 
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TlIROW_ AND SlGNAL_ 

The most basic of the debugging tools available are 
Throw. and Signal.- The Throw_ macros should be used when 
a problem occurs that must Ixj handled (for example, if the 
application runs out of memory). The Signal. macros should 
be used when a problem occurs which (while unexpected) 
should not cause a problem in the final version (for example, 
if MacsBug is not installed). You can find a number of Throw, 
and Signal, macros in the header file U Exception, h. 

The Debug.Throw macro determines the behavior of 
Throw_ and the Debug.Signal macro determines the behavior 
of SignaL- If Debug.Throw is undefined, then Throw_ will 
cause a C++ exception to be thrown. If Debug_Srgnal is 
undefined, then Signal, will do nothing. On the other hand, 
if the macros are defined, the behavior of Throw_ and SignaL 
depend on a run-time variables of Lype 

type enum ( 

d ebugAc tion_No tiling, 
debugAction_Alert. 
d ebugAc tion_ Debugge t 
] EDebugAction: 

The current setting is established by calls to 
SetDebugThrowJ) and SetDebugSignal.O- In the case of 
debugAction Nothing, the behavior will be the same as that in 
the Final build. In the case of debugAction_Alert } an alert will 
be displayed. Once the alert is displayed you can choose one 
of the following options: Log, Quiet, Quit, Debugger, 
Continue. Choosing Log will log the exception to a log file. 
Choosing Quiet will change the setting to 
debugAction.Nothing. Choosing Debugger will drop into your 
debugger (but not change the setting). Choosing Quit will 
quit the application and choosing Continue will continue 
execution, in the case of debugAction.Dsbugger you will l>e 
dropped into the debugger. You can learn a lot about how 
these work by using the Throw and Signal items in the Bad 
Things menu while changing the behavior with the 
gDebugThrow and gDebugSignal items in the Debugging 
menu (the one whose title is a bug icon). You should also 
experiment with the StDisableSignal.Q and StDisableThrowj) 
objects which temporarily disable this behavior (examples 
are available in the Bad Things menu). 

Debug New 

DebugNew is a collection of routines to help you debug 
your application for memory errors (leaks, overwriting arrays, 
dangling pointers). The call to DebugNewForgetLeaksJ) in 
main() tells DebugNew to forget all allocations made prior to 
that point in the application. The call to 
DebugNewReportLeaksJ) will wriLe out a log file indicating 
every memory allocation which has not been released up and 
ShowleaksO will open this log file if it contains information 


about any leaks. If you play with the Leak with NEW and Leak 
with new menu items and then quit the application (while 
leaving CodeWarrior running), the leaks log should open. In 
it you can see that by calling NEW you will get the file name 
and tine number where the leaked memory was allocated. 
The leaks from new are also recorded, but you get no 
information about where they occur. 

The macros DELETE and DELETE_ARRAY can be used in 
place of delete and delelefi and they will delete the pointer 
and then set it to nil. All the error handling has been built 
into the delete operators so you can use them if you prefer 
The two DELETE macros replace the DisposeGL macros 
provided by PowerPlant for two reasons: first, most of the 
error checking was redundant when using PP^DebugNew.cp 
and second, the non-redundant error checking was 
incorrectly written. 

You should play with the various memory related menu 
items in this section of the Bad Things menu to get a feel for 
the type of information DebugNew can provide. One thing I 
have noticed is that if the pointer is determined to be invalid 
by DebugNew, its memory will not be reclaimed w'hen you 
call delete. This means that overwritten arrays or mismatched 
new/delete calls will add lines to your leaks log. Fixing the 
overwrite or mismatch problem will fix the leak, 

LDebugStream 

The LDebugStream class is designed for streaming debug 
information to a variety of locations. The most common 
location would be a log file, however, you can also stream to 
a Throw., Signal, or directly to the debugger. If you enable 
streaming to a console (as I did in this application), you will 
be able to stream to a console window of your application. 
The original implementation required conditional 
compilation in your source code between your Debug build 
and your Final build. I have removed the need for that by 
adding no-op implementations in LFinalStream.cp (which is 
compiled and linked in the Final builds). 

The Bad Things menu has a number of items that stream 
to various locations. You will need to be careful when 
streaming into a Throw_, SignaL or to the debugger since 
these have a limited amount of space to display the 
information. Streaming to a console has some limitations 
also. If the console is on the screen, all command-key 
combinations are sent to the console first (before the 
CDocumentApp can act on them). In the case of many 
commands, the console will ignore them and rhe commands 
will get lost. You can see this by first streaming to the 
console and then typing command-N. A new window will not 
open as long as the console window is the front window. 

Given the above limitations, you mighi guess that most 
of your streaming will be done to a file and you are probably 
right. All of the streaming from within the PowerPlant classes 
is done to a log file that will be placed in the same directory 
as your application. 
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Other Debugging Menu Options 

That finishes the Bad Things menu, hut there are a few 
items in the Debugging menu which deserve mention. The 
Command Chain window provides you with a visual 
representation of the commanders in the application (these 
were discussed in the previous article), it would he nice if it 
also listed all the attachments since they affect the command 
handling hut I'll leave that modification as an exercise for the 
reader. We will discuss the Visual Hierarchy menu item next 
week, but if you play around with it, you can probably see 
figure out what it does. There are a number of Heap Routines 
for Compacting and Purging the Heap (on command or at 
regular intervals). These can be useful for stress testing your 
application. It would be nice to have a similar repeater for 
DcbugNew Validate All, but again, III leave this as an 
exercise for the reader. 

finally, you can use the Eat Memory... item to determine 
how your application will handle in low memory situations. 
One way to do this is Lo use the Launch Zone Ranger iLcm, 
check the number of free bytes in the application, round down 
to the nearest 100(1 and then eat Lliat much memory. This 
should cause the application to put up a low memory warning. 

Concluding Remarks 

We’re slowly putting together an application that will be 
able to do something. Although this month's article seems 


somewhat off the shortest path, the tools in the Debugging 
menu will help with some of the topics planned for the third 
article (windows), A natural question that arises now (if* not 
earlier) is; How much longer until I can really do something? 
My prediction is after the next three articles (windows, files, 
dialogs) you should be well on your way. If you can’t wait 
thaL long, try reading some of The PowerPlant Book. 

Power Pi jv nt References 

References that are particularly appropriate for this 
article are the following: 

■ "Applications and Events” chapter in The PowerPlant 
Book (it has a section on debugging) 

■ 44 Debugging in PowerPlant" chapter in PowerPlant 
Advanced Topics 

* John C. Daub's “Modifying Objects at Runtime in 
PowerPlant" in MacTech, March 1999 

* John C. Daub's “PowerPlam's Debugging Classes” in 
MacTecb , May 1999 

* FP^DebugMacros.h, UDebugNew.h. UHeapllttls.h, and 

UOnyx.h header files. Ml 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Wired 


Using Wired Actions in Sprite Movies 


Introduction 

in i he past two QuickTime Toolkit articles, we T ve learned 
how to create movies with sprite tracks. We’ve also learned 
several ways to animate the sprites in those tracks, first by 
adding override samples to the sprite track, and then by 
adding a video override track or a tween track to the movie. 
In both cases, we animate the sprites by changing one or 
more of the sprite properties (image index, matrix, graphics 
mode, and so forth). Our sprite animations so far have been 
pretty simple, but in fact we now have the ability to create 
some fairly complex sprite animations. For instance, we 
could add several tween tracks to a sprite movie, one that 
changes a sprites position (by tweening its matrix) and 
another that facies the sprite in and out (by tweening its 
graphics mode). Throw in a background sprite and a video 
override track and we have all the makings of a reasonably 
compelling animation. 

What we don't have, yet, is any way for the user to 
interact with Lhc animation (other than simply starring it and 
topping it using the controller bar). To be truly compelling, 
our movies should allow the user to manipulate sprites in the 
movie, or trigger changes in the movie by clicking on a 
sprite, or maybe even open a well site in a browser window 
when the user moves the cursor over a sprite. All of this is 
possible using one of QuickTime’s most powerful features: 
wired actions. In this article, were going to see how to 
attach (or "wire") interactive, dynamic behaviors (that is, 
“actions") to parts of a sprite movie. 

Consider, for example, die movie shown in Figure 1 
This looks just like die moving icon movies that we 
constructed last lime (except dial now we've used the current 
QuickTime extension icon and there is no controller bar on 
the movie window). 



Figure t; An icon sprite movie 

Bui appearances can be deceiving, for lurking within the 
movie are several new and interesting behaviors. When we 
move the cursor over the icon sprite, the cursor automatically 
changes into an open-hand cursor (Figure 2), which might 
suggest that we can drag the icon around. Indeed we cam if 
we hold clown the mouse button and drag, the sprite Is 
dragged along with the cursor, which changes info the closed- 
hand c ursor (as shown in Figure 3k when we release the 
mouse button, the icon sprite remains ai dial new position. 



Tim Monroe Ls still trying to figure out how to add wired actions to his lizards, They just sit and bask all day. You can send your ideas to him ai 
monitx-@apple.com. 
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Or consider the movie shown in Figure 4. This movie consists 
of a video track, a sound track, and a sprite track. There arc 1 six 
sprites in die sprite track, and each sprite is wired to duplicate one 
of die behaviors of die buttons in the standard controller bar. (From 
left to right, clicking on the sprites performs these actions: go to the 
beginning of the movie, go backward one frame, start the movie 
playing, pause the movie, go forward one frame, and go to die end 
of the movie.) As you am see, the movie has no controller bar, since 
we on now control the movie using the spriLe “buttons" alone. 



Figure 4: A sprite track that controls a video track 

You might be wondering what’s so special about all of this. 
After all, in our first sprite article (“A Goofy Movie" in MacTech, 
March 20011, we saw how to move sprites around and respond 
to mouse button clicks on them. At that time, all we did was 
change the visibility state of the sprite, but it would have been 
easy for us instead to repeatedly change the position of the sprite 
until the mouse button was released (and hence drag it around 
the movie), 'llie important difference is that there we used a 
special application (QTSprites) to supply those capabilities, 
whereas here we shall build a movie file that can be opened by 
any QuickTime-savvy application and that will have the same 
behaviors in that application as well. In oilier words, the 
dynamic, interactive behaviors are stored in the movie file as pan 
of the media data, not supplied by the playback application. 


Our sample application this month is called QTWiredSpritesJr 
(because it T s a stripped-down version of an existing sample code 
package called QTWiredSprites), Figure 5 shows the Test menu of 
QTWiredSpritesJr Hie two menu items allow us to add the 
controller sprite track to a QuickTime movie and to create the 
movie with a draggable sprite shown in Figure 1. This might not 
seems like a lot, but it will occupy us for quite a while. So sit back 
and take a deep breath. And get ready to have your QuickTime 
abilities changed forever. 


Test 


Add Control Sprites To MouSe... 

Make Draggable Icon Mouie... 

Figure 5: The Test menu of QTWiredSpritesJr 

Events, Parameters, Actions 

A wired sprite is a sprite to which one or more event atoms 
have been attached. An event atom is a QuickTime atom that 
associates an event with one or more actions that are triggered 
when that event occurs. Each action can have one or more 
parameter s, which specify any additional information that’s 
necessary for the action to performed. In addition, an action 
may have a target, which is the object upon which the action is 
performed. The structure of a typical event atom is shown in 
Figure 6, Here, the event atom contains a single child atom, of 
type kAction. this action atom, in turn, contains two children, 
one that specifies Lhe type of Lhc action and another that 
specifies the single parameter to that action. Some actions have 
more than one parameter, and some have none. 



Figure 6: 7he structure of an event atom 
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An event atom is attached to a particular sprite by 
including the atom as a child of the sprite atom (lhaL is, the 
atom of type kSpriteAlomType) and hence as a sibling of the 
sprite property atoms. Notice that the event type is the atom 
ID of the event atom. 

Specifying Events 

When wired sprites were firsL introduced (in QuickTime 
3.0), there were seven basic types of events that could trigger 
wired sprite actions, defined by these constants; 

enum | 

kQTEvcn t MouseClick - FGUR_CHAR CODE(*clIk'), 

kqa'EventHouseCXickEnd " FOUR CHAR .CODE (‘ cend 1 ). 

kOl'EventMouseCiickEndTri^erButton = F0UR_CHAR_C0DE( ‘trig')* 
kQTEventHouseEnter • F0UR_CHAR_C0t>E (* ent r ’ }* 

kQTEveotMouseExit “ KOUR_CIiAH„COOE U exit *). 

kQTEventF r fliaeLoad e<i = t'0UR_QHAK_L0DE (" t ram r ) . 

kQTEvpntiaiD = F0UHjCHAR_C0DE (* idle *) 

); 

Five of these actions concern various states of the cursor and 
the mouse button. When the cursor moves over any non-transparent 
part of a sprite’s image, die kQTEventMouseEnter event is issued 
(whether or not die mouse button is down), and when die cursor 
then moves out of the sprite, the kQTEventMouseExit event is issued. 
When the mouse Ixitton is clicked while the cursor is over a sprite, 
the kQTEventMouseClick action is issued, and when the mouse 
button is later released, the kQTEventMouseClickEnd event is issued. 
Note that die kQTEventMouseClickEnd event is issued whether or not 
die cursor is still inside of die sprite. If we want to make a wired 
sprite act like a button, then we can use the 
kQTEventMouseClickEndTriggerButton event, which b Issued only if 
die mouse button is clicked and released inside of the sprite's 
image. (This should remind you of the behavior of standard user 
interface buttons, which am nor triggered if the mouse button is 
released after die cursor is moved outside of the button.) 

When \ say here that one of these events is issued, I mean dial 
die sprite media handler looks for an event atom of that type inside 
of the sprite atom; if it finds one, then it interprets and executes die 
action atoms inside of that event atom. Only the action atoms 
associated with the affected sprite are executed, however. So, for 
instance, if two different sprites have actions associated with an 
event of type kQTEventMouseQick, then only die actions in the event 
atom of the sprite actually clicked on are executed. If two sprites 
happen to overlap, die event is .sent to the topmost sprite (die one 
with the lower layer property). 

The kQTEventFrameloaded event is issued when a sprite 
track key frame is loaded. It is not sent to any particular sprite 
and hence the event atom diat holds die associated actions is not 
contained inside of any sprite atom. Rather, die event atom is 
stored in die media sample atom container, as a sibling of the 
sprite atoms. Frame-loaded events are handy for initializing the 
state of the sprites in the frame. (More on this later.) 

Finally, the kQTEventldle event is sent to every sprite in a 
sprite track periodically, after some predefined number of ticks 
(that is, sixtieths of a second) has elapsed. The frequency with 
which these idle events are issued is determined by die 


kSpriteTraekPropertyQTfdieEventsFrequency property of the sprite 
track. Tills event is especially useful for triggering actions after 
some amount of time has elapsed; it will be very useful to us, 
for instance, when we build our draggable sprite movie. 

Subsequent versions of QuickTime have added several 
more event types, but we will not consider them in this article. 
The most interesting one, perhaps, is the event type 
kQTEventKey, which is issued when keys on the keyboard are 
pressed. In an upcoming article, well play with some of these 
additional event types. 

Specifying Actions 

Okay, so now we know how to get a sprite to stand up and 
take notice when certain kinds of events occur: we put an event 
atom with the appropriate atom ID into the sprite atom (as a 
sibling of the sprite property atoms that are inside the sprite 
atom). And we know what happens next: all the action atoms 
contained inside that event atom are interpreted and executed. 
So all we really need to learn is what kinds of actions can be 
triggered by QuickTime events. That is to say, we need to learn 
what values we can use as the data in an atom of type 
kWh ich Action (see Figure 6 again). 

Here comes the really good news: the latest Movies.h file 
cantatas over one hundred constants that we can use to specify 
action types. There are action types for setting a movie’s volume, 
and setting a sprite's image index, and setting a track’s graphics 
mode, and opening a URL in the user’s default browser, and on 
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and on. And every one of them can he wired to any one of the 
available QuickTime events. So we could scl up a sprite track in 
which dragging a c ertain sprite from right to left changes the 
balance of die movie’s sound track, or moving the mouse over 
a certain sprite changes the current pan angle of a QuickTime 
VR node. Really, the sky’s the limit. 

The available actions are best categorized by the 
target of the action (that is, the object that is affected by 
the action). QuickTime currently supports three kinds of 
targets: movies, tracks, and sprites. There are also some 
actions that have no target. 

A large number of actions perform operations on a movie. 
By default, the target of these action is the current movie (the 
one that contains the sprite track), but it’s also possible to target 
other movies. Here’s a representative sample of actions that 
operate on movies: 


eniim I 


kAc t i o nMo v i eS et Vo,l umu 

= 1024, 

kActionHovieSetRate 

= 1025, 

kAc t i otiilo vi e £e tLoop in&F lags 

= 1026, 

kAc tionMovieGoToTinte 

“ 102/, 

kAc tionMovieGoTnTimeByName 

- 1028. 

kAc t ioriHo v i e£k>ToBe& inning 

= 1029. 

kAc tin nMovie GoTu End 

- 1010, 

kAc tionKovieStepForward 

= 1011. 

kA ctionMovieSt epEa c kwa r d 

= 1052, 

kActiotiMovieSetSelect ion 

= 1033 


l 

A number of actions operate on tracks within a movie. 
The default track is the one that contains the sprite that 


triggers the action. Here are all the currently-defined actions 


that operate on tracks: 


enuas 1 


kActionTrackSetVolume 

- 2048, 

kAc tionTracksetBalance 

- 2049, 

kAc tionT r ac kS etEnabled 

= 2050, 

kAc t ionTrackSetMat rix 

- 2051. 

kAc tionT racks etLayer 

“ 2052, 

kActionTrackSetClip 

- 2053, 

kActloriTcackSet Cursor 

- 2054 * 

kActionTrackSetGraphicsModc 

t 

- 2055 

Of course, some of these actions make no sense if applied to a 
sprite trac k (for instance, kActionTrackSetVolume). In those cases, 

we need to specify some other track a 

is the target of the action. 

We'll see how to do that in the next article, 

A number of actions operate on sprites in a sprite track, Ibe 
default sprite is the one that contains the event atom that triggers 
the action. Here’s a handful of actions that operate on sprites: 

emim 1 


kAc tionSprit eSetMatrix 

= 3072, 

kAct1anSpriteSetImageIndex 

- 3073, 

kActlonSprIteSetVisdbie 

- 3074. 

kAc ti ci nSp c 11 eSe i Lay e r 

- 3075, 

kAc tionSpri t eSe tGraph 1 c sMorJ c 

» 

- 3076 

Finally, a fair number of actions 

have no target at all. A 


good example here is kActionGoToURL, which opens the user’s 
default web browser and loads a URL 
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Specifying Parameters 

How does the kActtonGoToURL action know which URL to 
open? The URL is specified in a parameter atom that is a child of 
the kAction atom. The number of parameters required by each 
action and the type of data in those parameters is detailed in 
Apple’s technical documentation on wired sprites; it’s also listed 
in Movies.h f for example like this: 

kActionGoToURL = 6146. f* (C string unl ink) V 

This tells us that the kAction Parameter atom in the action atom 
must contain a NULL-terminated string of characters that 
specifies the URL to open. 

Other actions take more than one parameter. For 
instance, the kActionMovieSetSelection action requires two 
parameters, a TimeValue that indicates the beginning time of 
the selection and another that indicates the ending time of the 
selection. In this case, the action atom must contain two 
atoms of type kAction Parameter, one with atom index 1 and 
the other with atom index 2. 

Controlling Movies Using Wired Sprites 

That's enough theory for the moment. Let's get started 
wiring some sprites, and let’s begin by seeing how to build the 
sprite track shown in Figure 4, which allows the user to control 
a movie by clicking on rhe sprite “buttons”, lliere are two main 
steps involved here: first we need to build Lhe sprite track 
(which contains the sprite images, sprites, and initial sprite 
properties), and then we need to wire those sprites with actions. 
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Building the Sprite Track 

We’re already pretty adept at building sprite tracks, so we can 
proceed quickly here. In the present case, we're going to add a 
sprite track to an existing movie, so we’ll start by getting some 
information about that movie, including its duration and size: 

GetMovieBox(theMovie, kmyRect); 
myWidth = Long2Fix{niyRect. right - myRect.left): 
myHeight = Long2f?ix(myRect.bottom - myReot .top): 
myDuration = GetK£wieDLfcrattDn(theMovle): 
myTiraeScale = GetMovieTLnGScale(theMoyie); 

Well use these values to set the size (and later the duration) 
of our new sprite track, like this: 

myTrack = NewMovieTrack(theHovie. myWidth* myHeight, 

kNoVolume); 

tnyMedia = NewTrackHedia(myTrack, SpriteMediaType. 

myTimeScale, HULL, 0); 

Now, of course, we need to add some sample data to die 
new sprite track. As you know, this data includes the sprite 
images and initial sprite properties* At this point, the 
QTWired AddSpriteControllerTrack function calls another 
QTWiredS pritesj r function, 

QTWlred_AddControllerButtonSamplesToMedia : to add the 
appropriate media data: 

QTWired_AddCont rol1Gr&ulL onSampleSToMedia{myMedia, 

toyRect,right - myRect.left* uyRect.Bottom - myHect.top* 
myDuration); 

Let's pause and reflect for a moment. We want the sprites in our 
sprite track to act like buttons, so that clicking on one of the sprites 
triggers some appropriate action. We also want the sprite image to 
change while the mouse button Ls held down over the sprite, in just 
the same way that a standard button changes its appearance when 
clicked. Figure 7 shows the movie when the user clicks and on the 
“Flay” sprite and holds the mouse button down. 
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Figure 7: We button down image for the “Play” sprite 
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So really we need two images for each sprite, one to be 
displayed when the sprite Is in the normal state and one to be 
displayed when the sprite Is in die "pressed” state. Figure 8 shows 
the twelve images that we are going to add to the sprite track. 

i 1 tB i i i 

ID ED H ED □ ED 

Figure 8 The sprite images 

If we store these images in consecutively numbered PICT 
resources, we can add them all lo the sprite key frame sample 
with these lines of code: 

for (myCount * 0: myCount < kNumCont roller Images: myCount H) 

Sp r i tetftils AddFICTTmageTolCeyF rstneSample (mySsmp] e. 

kFirstControllerlmiigelD +■ ntyCount t &myKeyColor, 
myCount + 1. NULL, NULL); 

Now let’s set the initial properties of the six sprites. For the 
“Go-To-Start” sprite (the first button on the left), we can use the 
code in Listing 1. 

Listing I: Setting the properties of the "Go-To-StarT sprite 

QWi rcd_A<ldCon r mile rButtonSampIesTt Media 

raySixth = lheTrackWidlh / kNumConLroHerButLons: 

myErr = QTNewAt onContainer (imySta rtButton); 
if (tnyErr != noErr) 
goto bail; 

myLocation.li = {kToEeginSpriteFoBition * mySixth) + 

((mySixth kfiuuonWldLh) / 2): 

nylocatlon.v * thcTracLHcighl fkButtor [Height + 5); 

^Visible = true; 

my Index = kToBeglnUpIndex; 

myLayer = 1; 

SpriteUtils .SetSpriteData(myStartButton, fonyLocation, 

&isVisible, imyLayer. ^mylndex. NULL* NULL, NULL); 

Sp tit elJtil s_Ad d S p r 1 teToSampl e (mySarapl e. my Sta r tflut ton, 
kToBogiiiSprileAlomlD) ; 

The only mildly tricky thing here Is the code we use to 
determine die horizontal position of die sprite. We first calculate 
one-sixth of the track width and then move over the desired number 
of sixths; then we back up fust enough that the sprite image is nicely 
centered in the appropriate sixth of the sprite track. 

If we repeat die steps in Listing 1 for the remaining five sprites, 
add the key frame sample to die media, and add die media to die 
track, the original movie will then have a new sprite track with die 
sprites laid out as shown in Figure 4. Of course, clicking on die 
sprites won't have any effect, since we haven’t yet attached any 
actions to ihose sprites, let's see how to do that. 

Wiring Actions to Sprites 

To wire some actions to a sprite, we need to add one or 
more atoms of type kQTEventType to the sprite atom and then 


add one or more action atoms to each of those event atoms. In 
the case of the M Go-To-Start w sprite, we want to add three event 
atoms, each of which contains a single action atom; 

■ When the mouse button is clicked and the cursor is over the 
sprite, we want lo change the sprite's image index property 
so that the "pressed” image is the current image. That is, we 
want to change the image to kToBeginDownlndex, 

• When the mouse button is released (whether or not the 
cursor is still within the sprite), we want to change the 
sprite's image index property so that the normal image is 
once again the current image. That is, we want to change the 
image back to kToBeginUpindex. 

• When the mouse button is released and the cursor is still 
within the sprite, we want to execute the 
kActionMovieGoToBegirming action. 

Listing 2 shows some code that we can use to handle mouse 
clicks on the "Go-To-StaiT sprite. 


StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more ! 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your fable ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 

In-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today 1 

Only $200.00 MasterCard A Visa accepted. 

StoneTable! Publishing 
More Info A demo Vorce/FAX (503) 287-3424 

http i//www .teleport.com/-stack stack@teleport.com 


May 2001 • MacTbch 










Listing 2 : Handling mouse clicks on the "Go-To-StarT 
sprite 

QTWifwi_ At JdCon trolliTRi a tonSa mplesToMedia 

myErr = QTlnsertChild(myStartButton, kParentAtomlsContainer. 

kQTEventType, kQTEventMousedick> l r 
0, NULL. amyEventAtora]; 

if (myErr noErr) 
goto bail: 

// add an action atom to the- event handler 

myErr = QTi‘1 n^g^t Child {tny St art But ton. my Event Atom. kAction, G, 

0„ 0, NULL, &niyActtonAtora): 

if (myErr [= noErr) 
goto bail; 

myAction - EndianU32 KtDB(kActionSpriteSetliDagelndex); 
myErr " QTT tic ert Child (nyStartButtan, myAct Jon Atom. 

kWhichAction, 1, 1, sizeof(myAciion)t 
Action, NULL); 

if {inyErr != noErr) 
goto bail; 

// add a panuntfcr lo lilt sol image index action: image index 
my I nd ex = End la ntJ3 2_ Nt oB (kToBegi nDowrt Index); 
ttyErr = QTTnseftChiId(myStarrButton, myAct l onAtom t 
kAciionParameter, G, 

{short JkEirstParam, sizeof {my index] , 
Index. NULL): 

As you can see, wc add an event atom whose alom ID is 
kQTEventMouseClick to the sprite atom (myStartButton). Then we 
insert an action atom (of type kAction) into that event atom. The 
action atom is given iwo children, one of type kWhichAction 
whose atom data is kActionSpriteSetlmagelndex, and one of type 
kActionParameter whose atom data is kToBeginDownlndex In a 
nutshell t this says: when the user dicks on the “Go-To-Start" 
sprite, change that sprites image index to kToBeg in Down Index 
Listing 3 shows some code that we can use to handle 
mouse-up events tor the "Go-To-StarT sprite. The code is 
entirely analogous to the code in Listing 2: all that has changed 
is the ID of the event atom and the index of the image. 

Listing 3: Handling mousc-up events for the “Go-To-Start” 
sprite 

QTWired AddConttt jJkrButft >nS;impltsToMedia 

jnyEn - QTIrmertChild (myStfirtBut ton, kPar&atAtoroIfjCcjnraln(*r , 
kQTKvent Type. kOTEventBouseCl LckEtid * 

1, 0, NULL, &myEveiiLAlum) ; 

if (myErr != noErr) 
goto bail; 

// add an action atom to the event handler 

myErr - QT Insert Child (inySt.artBijtton. myEventAtom. kAction, Q. 

fl. 0* NULL, &tiiyAr.tionAtoin) ; 

if (inyF.rr !* noErr] 
goto bail; 

myAction ** EndianU32_NtoB(kActionSpriteSetImageIndex): 
myErr - QTInsertChiid(myStartButton, myActionAtom. 

kWhichAction. l t i. sizeof (myAction), 
&myAction, NULL); 

if (myErr 1= noErr) 
goto ball; 

// add a parameter to the set image index action: image index 
mylndex - EndianU32_NtoB(kToBeginUpIndex): 
myErr m QTInfiertChild(myStartButton. myActionAtom. 

kActionParameter, 0, 

(short)ktiratParam, sizeof[myIndex}, 
firayTndex. NULL) ; 


It T s actually even easier to wire the kAction MovieGoToBeginn ing 
action to the kQTEventIVIouseClickEndTriggerButton event, since there 
are no parameters. Listing 4 shows how we handle tins. 

Listing 4: Handling button-trigger events for the “Go-To- 
Start* sprite 

QTWlrcd AddContnillLTBirttonSumpltsToMedia 

myErr ™ QTTnserLCbMri (myStarlftut ton . kFarentAtomTsContainer. 
kQTEventType, 

kQTEventMouseC1ic kEudi'ri gger fl uI Ion, 1, 
0. NULL. fcmyEyeutAtom); 

if (myErr != noErr) 
goto bail; 

// add an action atom to the event handler 

myErr - QTTnsertChiId (myStartButton, myFventAlotn, kAction, fi t 
0, 0, NULL. kmyActionAloin}; 

if [myErr 1= noErr) 
goto bail; 

myAction ^ EndiahU32_NtoB(kActionMovleGoToBeginning): 
myErr = QTInsertChildfmyStarfButton, tayActionAtom, 

kVh1chActIon, i, l. sizeof(myAction), 
imyAcUon, NULL); 

So adding simple wired actions to sprites really is just another 
exercise in constructing atom containers and atoms. Figure 9 shows 
the structure of the u G»To-Smrf sprite atom. (Note that several of 
the sprite property atoms have Ix-en omitted) 



Figure 9: 7 he ‘ (io- 7 h-Siu rt" sprite ah >m 


Setting the l rack Pro[>erties 

We still have a couple of things wc need to do lx4oie our 
movie is fully wired. For one thing, we need to indicate that the 
sprite track has actions In it. We do tills by including in the track's 
media pmjxfrfy atom an alom of type kSpritelrackPropertyH as Actions 
whose atom data is set to true. (For more discussion of media 
prr)peity atoms, see Lt A Goofy Movie”, cited earlier.) Listing 3 shows 
our definition of GTWired^SetTrackProperties, whic h is similar to the 
QTSprites SetTrackProperties function we used in previous articles. 
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Listing 5: Setting the sprite track properties 

QWircd SctlhidtPiopertks 


A layer is a value of type short, so the largest possible layer 
value is 0x7fff: 


void QTWi reci_SetfraC:kPropcrt les 

(Media theMedia, UIM32 theldleFrequency) 


fdefine kMaxLayerNumber 


0x7FfI 


QTAtomContainer 

RGBColor 

Boolean 

Hint32 

OSfcrr 


myTrackFroperties: 
myBackgroundCoior; 
hasActions; 
myFrequency: 
myKrr = noErt: 


// add a background color to the sprite frock 

myBackgEoundColor.red = EndianUl6_NtoB(0xffff): 
nyBackgroundColor.green - EndianU16_NtoB(0xftft); 
myBackgroundColor.blue - EndianU16_HtoB(0xffff); 

tnyErr = QTWewAtomContainer(SmyTrackProperties); 
if (myErr ™ noErr) I 

[JTInserl Child (myTrockProperties. 0. 

kSpriteTrackFropertyBackgruimdColur t 1, 1* 

sizeof(ny Backgrounds lor). &my Background tiler, NULL); 


Listing 6 shows our definition of the 
QTWired_GetLowestlayerlnMovie function. 


Listing 6; F indin g the lowest track layer in a mov ie_ 

QTWi rttl_Get lowest LayerfnMovie 

short QTWired_GetLowesiLayerInMovie (Movie theMovie) 

i 

long ary Count “ 0; 

long myTndex: 

short myLayer = 0; 

short myMinLayer = kMaxLayerNumber: 

tnyCount = GetMovieTrackCount (theMovie): 


U Ldl the movie controller Uui tills sprite Hack has actions 

hasActions = true; 

QTTnsert-Chl Id (myT rack Properties, 0 t 

kSprlteTrackPropertyHasActions, l, j, 
sizeof(hasActions) h &hasActions, NULL); 


for (mylndex - 1; mylndex <“ rnyCmmt; mylndex++) [ 
myLayer = GetTrackLayer(GetMovielndTrack(theMovie. 

mylndex)): 

if (rayLayer < myMinLayer} 
myMinLayer - myLayer; 

S 


// ldl the sprite track to generate Qildlcbvcnts 

myFrequency = EndianU3 2_NtoB f theIdleFrequency ); 

QTInse rtChiId(myTrackFroperties T 0 , 

kSpriteTrackPrDpertyQTIdleEventsFrequency t 1. l t 
s1 zoof(myFroquoney). imyFrpquency, NULL): 

SetMediaProper tyAtom(theMedia. myTrackPropc rLies): 

QTDisposeAtomContainer(myTrackP roperties): 

I 

\ 

You'll notice that GTWired_SetTrackProperties also adds an 
atom of type kSpritoTrack Property QT1 die Even Is Frequency to the 
media property atom. As we mentioned earlier, this atom 
specifies the number of ticks between idle events. Our current 
sprite track doesn't use idle events, so we pass rhe parameter 
kNoGTIdleEvents, which tells the movie controller not to issue 
idle events at all. Another useful value is 0, which tells the movie 
controller to issue idle events as fast as possible. 

Setting the Track Layer 

Each track In a movie has a law?, which determines the 
order in which ihe track is drawn into the movie. Tracks with 
lower layers are drawn after tracks with higher layers, so they 
will be drawn on top of those higher-layered tracks. When a 
track is created, its layer is set to 0. Tn the current case, we want 
to ensure that our new sprite track is drawn on top of all existing 
tracks in the movie, since otherwise it might be hidden behind 
those tracks (and hence lie pretty much useless). So we need to 
get the lowest track layer of those existing tracks and then set 
the sprite track's layer to some lower value, QTWiredSpritesjr 
does that with these lines of code: 

SetTrae kLaye r (rayT rack. kMa xLa y e t Numb e r); 

S etTr a c kLa y e r{ rayT r ack, 

QTWi r ed_. Ge tLowes t Lay er I nMovief theMovie} - 1); 


return(myMinLayer): 

\ 

Setting the Movie Controller 

One thing that's distinctive about a wired sprite movie is 
that it must be associated with a movie controller. It’s the movie 
controller’s job to determine whether a sprite track contains any 
event atoms and then to monitor the mouse and keyboard for 
any relevant events. When any of the designated events occur, 
tlie movie controller sends them to the appropriate sprites. 

Hi is of course Ls not a problem for us. All of our sample 
applications (except for one) use movie controllers to manage Lhc 
users interactions with a movie. WeVe seen, sufficiently I hope, that 
using movie controllers can .save us a tremendous amount of work. 

There is, however, one troubling issue that arises here. By 
default, Lhe standard movie controller displays the controller bar 
(usually along the lx>ttom edge of the movie). But in some cases we 
might not want the controller bar to lx* displayed. This is especially 
true in the case of the movie lhaL we just built; after all, what's the 
point of devising our own sprite buttons for controlling a movie if 
we're saddled with the standard controller bar? 

To address this issue, QuickTime 3.0 introduced a new type 
of movie controller called the no-interface movie controller (or 
sometimes the none movie controller ), The no-interface movie 
controller operates just like the standard movie controller except 
that no controller bar is displayed and no keyboard events are 
passed to it. (Also, we cannot display a badge on a movie that's 
associated with the no-interface movie controller, but dial's sort 
of a corollary of the fact that no controller bar is displayed,) 
The no-interface movie controller is made to order for 
movies in which we used wired sprites to handle user 
interaction with rhe movie or with iLs dements. But how do we 
tell QuickTime to use the no-interface movie controller for some 
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particular movie? We do this by attaching a user data item of 
type kUserDataMovteControllerType to the movie, whose item data 
is FOUFLCHAR CODE('none'), like this: 

OSType myType = FOUR CHAR_00DE(* none ')- 

ntyType = EndianU32 NtoB(myType}; 

SetUsetDataltemtGetMovleUserData(theMovie), fcmyType, 

(myType). kUserllataMovieContronerType, 1); 

(Tiie value FOUR._CHAR_CODE( 4 none') is the component 
subtype of a movie controller component. Unfortunately, there 
is no constant defined in any of the public QuickTime header 
files for this value.) 

When an application calls NewMovieController to attach a movie 
controller to a movie, NewMovieController Hist kxjfts for a movie user 
data item of type kUserDataMovieControllerType and, if it finds one, 
tries to open an instance of a movie controller component having 
the sulxypc specified by that items data. This occurs transparently 
to the application (which is why existing applications arc able to 
play wired sprite movies using the no-interface movie controller), 

Setting the Track Matrix 

It s time for a small but important digression. Recall that we 
determined the size of die new sprite track by calling 
GelMovieBox. like this; 

GetMovieBoxftheMovie. &myRect); 

myWidth - Long2FiX(myRedt. right myRect.left); 

snyHeight “ Long 2 Fix (fay Refit .bottom myRecL .top); 

This method works in almost all cases — Fd venture to guess that it 
will work for at least Wo of all existing QuickTime movies. But in 
a few cases, it fails miserably. Figure 10 shows wliat Imppcns if we 
try to add our sprite button track to the toy train movie we 
encountered in an earlier article. 
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Figure 10: 1he toy train movie after adding the sprite button track 

To understand wliat’s causing this problem, and how we can 
avoid it, we need to delve a bit deeper into a movie’s geometry. 
When a track’s media handler draws some data, it draws it into the 
rectangle (called the fmek rectangle) defined by the track's 
dimensions. 'Hie coordinate system in which die point (0,0) Is at the 
upper-left corner of the track rectangle defines (he track coordinate 
system. When a track is composited into a movie, the track data Is 
transformed using a track matrix which maps the track coordinate 


system into the movie coordinate system Bui before die movie data 
is displayed on die output device, that data Is trunsfonned once 
again. QuickTime applies the movie matrix, which maps the movie 
coordinate system into die display coordinate system (namely, the 
QuickDraw global coordinate plane)* 

In most cases, die track matrices and the movie matrix are the 
identity matrix, so we can safely ignore these various 
transformations. But a movie can have a non-identity movie matrix. 
The toy train movie Is one such movie, and that's what causes die 
problem seen in Figure 10. The GetMovieBox function gives us die 
sixe and location of the movie in display coordinates, after the track 
and movie matrices have been applied. Using the movie box to 
determine the dimensions of die sprite track is guaranteed to 
produce the wrong results if the movie has a non-identity movie 
matrix, since die track rectangle is always transformed using that 
matrix before being drawn to die screen. 

A solution to this problem Is actually fairly simple. All we 
need to do is compensate for the movie matrix by calculating die 
inverse of die movie matrix and installing it as the sprite track's 
track matrix, like this: 

CetHo vleHat t ix (theMovi e , kray Ha t r i *); 
if (InverseKatrix(&myMatrix, imyTnverseMatrlx)) 
SetTrackMatrixfmyTrack, fonylnvemeHatrix); 

The InverseMatrix function returns, in the second parameter, the 
inverse of the matrix specified by Lhe first parameter If it 
succeeds in inverting the first matrix, it returns true (and false 
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otherwise). So the sprite track's track matrix and the movie 
matrix essentially cancel each other out, which is sufficient to 
place the sprite track in the right place. 

One moral of this story is that it's good to test our code on a 
wide variety of movies to make sure that it h s able to handle pretty 
much anything the user might throw at it. It's perfectly legal — 
albeit rare — For a movie to have a non-identity movie matrix. So 
our applications should txr smart enough to handle them 
correctly. A particularly useful collection of “non-standard” movies 
can he found on the QuickTime 3.0 SDK CD, in the folder titled 
"Archived Interesting Movies”. That collection contains movies 
with non-identity track matrices, non-identity movie matrices, and 
a handful of other oddball characteristics. Testing our code on 
these movies can often reveal some design flaws in our logic. 

Putting It All Together 

Listing 7 shows our complete definition of the 
QTWired_AddSpriteControl1erTrack function. 

Listing 7: Adding a sprit e con troller track to a movie 

QWired AddSpritcControllcrTrack 

OSErr QTWIred AddSpriteContnJllerTracI (Movie theMovie) 

I 


Track 

myT rack = NULL: 

Media 

myMedla = NULL: 

MatrixReeord 

myMai.rlx: 

RGBColor 

myKeyColor: 

Fixed 

ray Width, mylteighl; 

Reel 

myRect: 

TimeValue 

rayDuration “ 0L: 

TimeValue 

myTimeScale * 0L; 

OSType 

myType = FOUR„CHAR_CGDE(* none *}: 

OSErr 

myErr - noErr; 

If (theMovie 

— NULL) I 


myErr = paramErr: 
goto bail; 

) 

// get some information about the target movie 

GetMovieBox(theMovie. Rect): 

myWidth - Long2Fix(myltecl + right - myRect.left); 

myHeight “ Long2Fix(myKect.bottom - my Reel.top); 

myDuration = GetMovieDuration(theMovie): 

myTimeScale = GetMovieTimeSc a 1 e [ t heMovle); 

// create a new sprite track in the ur^ei movie 

myTrack = NevMovieTraekCtheMovie, myWidth, mylleight. 255); 
myMedia = NewTrackMedla(myTrack, SpriteMediaType. 

myTimeScale, NULL . 0] ; 

// set the track matrix to compensate for any existing movie matrix 
Ge t Mo vi aMat r ix (t hefiov i e, f*my Matrix); 
if (InverseWatrix(&myMatrix. fitiny Inver seMatrix)) 
SetTrackMatrix(myTrack, &myInverseMatrix); 

myErr = BeginMedi&Edl ts(rayMedia); 
if [myErr !** noErr) 
goto bail; 

// add sprite images and sprites to the sprite trick; add actions to the sprites 

OTired_AddControllerButtonSarapXesToMediEi(tnyMedia, 

my Rec t .right - inyRect. left. inyRect .bottom myReet.top. 

rayDuration); 

myErr “ EndMediaEdits(myMcdja): 
if (myErr 1 = noErr) 
goto bail; 

// add the media to the track 

InsertMediialntoTrac.k(myTrack. 0 + 0, 


GetMediaDurationfayMedia). fixedl); 

// set the sprite track properties 

QTWired_SetTrackPtopertiesCmyMedia, kHoQTIdleEvetrts); 

myKeyColor.red = myKeyColor.green = myKeyColor.blue = 
Oxffff; //white 

HediaSetGraphicsMode(GetMediaHandler(myMedia), transparent. 
&myKeyColor); 

H make sure that the sprite track is in the fronimost layer 
S e tT r ackLayer (myTr ac k, kMa xL aye rNutnb e r); 

SetTracklayer(myTrack, 

QTVired_GetLowestLayerInMovie(theMovie] - 1); 

// select the"no-interface" movie controller 

myType - EndianU32_NtoB(myType); 

Set Us etDat a Item (Get Mov leUserData (theMoviel. &myTy pe t 

sizeof(myType). kllserDataMovieControllerType. 1): 

bail: 

return(myErr); 


Wired Sprite Ummss 

You’ll notice tiiat 1 didn’t include the complete listing of the 
QTWired_AddControllerButtonSamp]esToMedia function. The 
reason for this should !xj clear from a brief glance aL Listings 2, 
3, and 4: adding simple button behaviors to all of the six sprites 
would require a total of about 200 lines of code. Obviously, for 
both readability" and maintainability, ir would behoove us to 
encapsulate parts of that function inio some reusable utility 
functions, in just the same way that previously we facilitated our 
work with sprites by using the functions in SpriteUtilities.c. For 
the most common operations with wired sprites, we can use the 
functions in the file WiredSpriteUtilities.c. In this section, we’re 
going to consider a few of those functions. 

Adding Event and Action Atoms 

In Listings 2, 3* and 4, we tx^gin by adding an event atom of 
the appropriate type to the existing sprite atom. At that point, since 
we’ve Just created the sprite atom ourselves, we know that it 
doesn't already have any event atoms in it T so we can safely call 
QTInsertChild to add one. More generally, it would lie better to 
look and see whether the sprite atom already contains an event 
atom of the type we want to add. If it does, then we can just add 
our new action atoms to dial event atom, If it doesn't, then we 
need to create a new atom of that type. Listing 8 shows the 
definition of die utility function WiredUtils.AddQTEventAtorn which 
returns to us either the exisLing event atom or a new event atom. 

Listing 8: Adding an event atom 

Wired! JtUs . AddQTEvintAtnm 

OSErr WiredUlil s_AddQTEventAtoni 

(QTAtoTnContainer theC container. QTAtom theAc ti onAtoms. 

QTAtomlD theQTEventType, QTAtom *tbeNewQTEvestAtom) 

I 

OSErr myErr - noErr; 

if ((LheContainer “ NULL) || (theQTEventType == 0) M 

{tbeNevQTEv onlAt ora => NULL)) \ 

myErr “ paramErr; 
goto bail; 

i 

If (theQTEventType “ kQTEventFraraeLoadad) \ 

UheMevQTE vent Atom = QTFindChildByrDftheContainer. 
theActdonAtoms, kQTEv enframe Loaded, L f NULL) ; 
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t r ( # theNew<3TEventAtoiB == 0) 

myErr » QTlnsartChlld (LheCuutainer. theAct lonAt-unis* 
kQTE vent Frame!-ofldetl* 1, 1, 0, NULL* 
theNewOTKvenLAtom): 

1 else i 

•rheNewQTEviMitAtosi - GTFindChi 1 <JBy ID £ tbeContainer * 

IheActionAtoms, kQTEventType, theQTEventType„ NULL): 
if (* t’heNewQTE vent Atom — 0) 

my Err * QTlnsertChild(theContainer. theActionAtoms. 
kGTEventType* thcGTKventType, 1* 0, NULL * 
t heNewQTEv e n t A l <tm ) j 
I 

bail: 

return (myErr) r 

I 


Notice iJiiil frame-loaded events arc treated differently here. 
The atom type of a frame-loaded event is kQTEventFrameLoaded 
(not kQTEventType. as with other events) and the ID should lx* 
1. Also* for frame-loaded events, we expect the caller to set the 
theActionAtoms parameter to kParentAtomlsContainer. so that the 
event is inserted as a child of the container atom. 

Once we have an event atom, we want to add one or more 
action atoms to it. As we know, an action atom is a parent atom 
dial always includes a child of type kWhichAction. We can use the 
WiredUtils^AddActionAtom function, defined in Listing 9, to add 
an action atom to an event atom. 


Listing 9= Adding an action atom to an event atom 

WiretlL ?tils AtkiActionAtoiii 

OSErr WlredUtil5_AddAetionAlom [QTAtooiCoDtainer theCoutainer, 
QTAtom theEventAton* long theAetionConstant, 
QTAlom * theNevAct ionAtfun) 

( 

QTAtosi ayActloDAtora “ 0: 

OSErr myErr » no£rr: 

if ((theContainer “= NULL) || UheActionConstant ^ 0)) I 
myErr = parajuErr: 
goto bail: 

I 

myErr = QTOtse r t Chi Id (theCoat aimer. theEventAtom* kAetion, 

0, 0. 0* NULL, knyActionAtom); 

if (myErr I* noErr) 
goto bail: 

thcActiuriConstant “ EndianUiZ_NtoB(theActioaConstant); 
myErr =■ QT Insert Child (theContainer, ary Act ion A tom* 

kWh E cliAc t i on * 1 1 1 * a i raof 11 he Ac t i onConatant) * 
it hoAc tiouCon s t an t. NULL): 

bail: 

if (theNewActlonAtom != NULL) I 
if [myErr !** noErr) 

*theftfevActionAtom ~ 0: 
else 

*theNewActf onALoio = myActionAtom: 

I 

return(myErr); 

* 


Actually, the value we pass for the Even l Atom can be 
kParentAtomlsContamer in which case the action atom is added 
as a child of theContainer. This will be useful later when we 
want to create complex wired actions involving conditional 
execution of actions* 


Wired$priteUtiUties,c defines the function 
WiredUtils_AddQTEventAndAction Atoms, which just calls 
WiredUMfs AddQTEventAtom and then W i red Util s_AddAction Atom. 

listing 10; Adding event and action atoms 

Wi iedl 11 iisjVdbQTEvrn lA nil Art ionAtoms 

GSEr r WiredUtils_AddQTEven tAndActionAtoms 

(QTAtomContainer LheContainet, QTAtom LheAtom* 
long theEvenl. long theAction* QTAtom *theActionAtom) 

I 

OTA ton myEventAtom * 0; 

OSErr myErr = noErr; 

toyEventAtom * theAton: 

if (theEvent !* 0) t 

myErr = Wi redUtilfi_AddQTEventAtoni(theCtmtainer* thaArnm* 

theEvc rs t, frmyEventAt om ); 

if (myErr t« noErr) 
goto bail; 

] 

myErr - WiredUtna_AddAutior^tomftheCofita Iner* myEventAtom, 

tbeArtion, theActionAtoto); 

bail: 

return(myErr): 

I 

To add a parameter to an action, we add a child atom of 
type kActionParameter WiredSpriteUtilities.c defines the function 
WiredUtils_AddActionParameterAtom, which just calls 
QTlnsertChild. Bear in mind that the data passed in die 
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WiredUtils^AddActionParameterAtom, which just calls 
QTInsertChild Bear in mind that the data passed in the 
theParamData parameter must l>e in big-endian format, since 
WiredUtils J^ddActionParameterAtom does not perform any byte 
swapping. 

Listing 11: Adding an action parameter atom 

VttrcdCtil5_AddActi<mPir4iii(.nerAtojTi 

OSF.r r WiredUtils_AddAc tiortPa raneterAtoa 

EQTAtomContainer theCont ainer, (TTAtotn theActitinAloin, 
long thePatanreterindex. long tbeParamDataSize. 
void "t.hnParaaiData, QTAtoin ^theNewParaniAtoEo) 

I 

C etu rn E QT1ns e rt C hi1d(theContaine i < theAc 11onAt om , 

kAc tioftPa r a me t er T 0, (short)theFarameterIndex. 
theParatflDa LaS l , theParainData. theNevFa raaAtom)): 

1 

Setting a Sprite Image Index 

Lets put these utilities to work for us. Listing 12 defines the 
WiredUtils AddSpriteSetlmageindexAction function, whic h adds to 
the sprite atom theAtom the children necessary Lu change the 
sprites image index in response to the event specified by the 
theEvent parameter. (For the moment, well ignore the call to 
WiredUtils AddTrackAndSpriteTargetAtoms, since our sprite actions 
in this article all use the default targets.) 


Listing 12: Adding a sprite index setting action atom 

Wired l fi ils_AddNpn leSetlny ^liukxAction 

GSErr WiredUtils_AddSpriteSfitTmageIndexActiGn 

(QTAtomContainer thoContaLner, QTAtom theAtom. 
long theEvent, long iheTmckTar get Type. 
void *theTrackTarget. long theTraekTypeIndex, 
long theSpriteTargetType, void *theSprit©Target, 
short thelmagelndex, QTAtora UheArtinnAtoni) 
l 

QTAtom tnyActionAiaro * 0: 

OSErr myErr “ noErr; 

tayErr ” WiredUtiXfi_AddQTEvetit-AndActionAtoas(theContainer. 

theAtom. theEvent, kActionSpriteSetImageIndex, 
AmyAotionAtom): 
if (myErr !« noErr) 
goto bail: 

theTJUagelndex “ EndianS l 6 _KtoE{ the Image Index): 
myErr = ViredUtiIs_AddActiDnParameterAtoiii(theContairier, 
piyActionAtom, kFirstParam, 
aizeof(thelmagelndex). &thelmagelndex. MULL): 
if (myKrr !-* noErr) 
goto bail: 

ptyErr “ tf i redU t i IsJWdTrackAndSprit ©Target Attics 

[theContainer. myActlonAtOEi, theTrackTargetType, 
theTrackTarget♦ tKeTrackTypalndex. 
th©Sprit©TargetType. LheSpriteTarget): 
if EtheAtlionAtom != NULL) 

•theActionAiom “ rayActionAtom: 

bail: 

ret urn(myErr): 

I 
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Now we can go back and rework some of our earlier code. 
In particular, all the code in Listings 2, 3, and 4 can be replaced 
by these lines: 

Wired,UtilB_AddSp rite Set ImagelndexActionCmyStartButton, 

kParentAtoral^Container, kQTEventMouseClick, 0. NULL, 

0,0. NULL, kToBeginDownIndex: t NULL); 

WiredUtils_AddSpriteSetImageIndexAction (myStartButton. 

kParentAtomlsContainer* kQTBventMouseClickEnd, 0. NULL. 

0. 0. NULL. kToBegiriUp Index, NULL); 

WiredUtila_AddMovieCoToBeginningActioo[ td/S tartButton. 
kParentAtomlsContainer, 
kQTEventMouseClic kEndTr i ggerButton): 


Variables and Conditionals 

In addition to the basic event-and-action interactivity 
that we've witnessed so far, QuickTime also supports what 
we might call program mable interactivity. That is to say, our 
wiring can make use of standard programming concepts like 
variables, function calls, and flow-control logic. In our wired 
actions, we can set and get the values of variables, read 
movie and system characteristics, and control the execution 
of actions using if-then 1 * and “■while" constructs. As you can 
imagine, this opens the door for some sophisticated and truly 
amazing wired actions. In practice, variables, environment 
checking, and flow control are always used in combination; 
so let's roll out the theory in this section and defer actual 
examples of their use until the next section, 

Setting Variables 

Each sprite track can have a set of variables — called 
sprite track variables — whose values can be set and read by 
wired actions. Variables are particularly useful for 
maintaining state information, such as whether a particular 
button is down or whether a sprite has reached a certain 
location in the movie. In QuickTime 3, the values of sprite 
track variables were always boating-point values; beginning 
in QuickTime 4, these values can be either floating-point 
values or NULL-term mated strings. 

We refer to a sprite track variable using a variable ID , 
which is of type QTAtomID. (A QTAtomID is declared as a signed 
long integer, of Lype long.) To set the value of a sprite track 
variable, we execute either die kActionSpriteTrackSetVariable or 
the kActionSpriteTrackSelVariableloString action, Both these 
actions require two parameters, the 10 of the variable to be set 
and the desired value of die variable (which is a floating-point 
value or a string, respectively), Listing 13 defines a function 
that we can use to set the value of a variable to a specified 
floating-point value. 


Listing 13; Setting a sprite track variable _ 

WlrcdUtits_AddSprireTrack5etVaria hit Act ion 

OSErr WiredUtils_AddSpriteTrackSetVariableAction 

(QTAtoraContainer theContainer. QTAtora theAtom. 
lon^ theEvent, QTAtomID theVariablelD. float theValue, 
lon^ theTrackTargetType, void + theTrackTarget, 
long theTrackTypeIndex) 

I 

QTAlom myActionAtom 0; 

OSErr ray Err “ noErr; 

myErr = WiredUtils^AddQTEventAndActionAtoms (theContainer, 
theAtom, theEvent. kActionSpriteTrackSetVariable, 
fcayActionAtoa): 

if (myErr 3= noErr) 
goto bail; 

theVariablelD = EndianU32_NtoB(theVariablelD) ; 

myErr = WiredUtils_AddActionParaineterAtom[theContainer, 
myActionAtom, kFirstParam. sizeof(theVariablelD)* 
itheVariablelD* NULL); 

if (myErr 1= noErr) 
goto bail; 

EndianUtils_Float_NtoB(&theValue): 

myErr = WiredUtils_AddActionParatneterAtom(theContainer* 
myActionAtom. kSecondParam. sizeof(theValue), 
itheValue, NULL); 

myErr = WiredUtils. AddTrackTargetAtQmftheConta 3 ner, 

my Ac tio nA tone thcTrackTargc tTy p e. i beTrackTa rget. 
theTrackTypeIndex); 

bail: 

return(myErr); 

I 


We can perform numeric operations on the values of 
floating-point variables by creating expression atoms (which well 
consider shortly). Also, we can concatenate the values of two 
string variables by executing the k Action SpriteTrackCon cat Variables 
action; this action requires three parameters, the variable IDs of 
die two string variables to be concatenated and die variable ID 
of the variable to which the result is to he assigned. 

Controlling Action Processing 

QuickTime supports two basic mechanisms for controlling the 
flow of wired action execution, the kActionCase action and the 
kActionWhile action. The kActionWhile action takes a single parameter, 
of type kCondrtionalAtomlype, This atom is a parent atom that 
contains two children, one of type kExpressionContainerAtomType 
and another of type kActionListAtomType The expression container 
atom defines an expression, as long as die expression evaluates to a 
non-zero value, the action list is executed. (An action list is simply a 
list of one or more action atoms.) Figure 11 shows the general 
structure of a kActionWhile atom. 
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Figure / /: The structu re of a while atom 


A case atom is slightly more complex than a while atom* In 
a case atom, there is exactly one parameter atom, which 
contains an arbitrary number of kConditionalAtomType atoms 
(which may have any unique atom IDs). When a case atom is 
executed, the conditional atoms are evaluated (starting with the 
atom with index !)■ when the expression In one of the 
expression atoms evaluates to a non-zero value, the associated 
action atom list is executed. Figure 12 shows the general 
structure of a kActionCase atom. 



Figure 12: The structure of a case atom 
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A case 'Atom is analogous to an "IT statement followed by 
some numlxT of “else if' .statements. We can therefore emulate 
an "if-then“ construct by creating a case atom that contains just 
one conditional atom. 

Using Expressions and Operands 

Now we need to understand how to construct an expression 
container atom. An expression container atom is a parent atom 
that contains either an operator atom or an operand atom. 
Operator atoms provide a means of combining operand atoms (or 
indeed other operator atoms) using numerical and logical 
operations* For instance, Figure 13 shows the structure of an 
expression container atom that adds two operands together* 
Notice that die atom ID of an operator atom specifies the kind of 
operation to perform* Notice also that the IDs of the child operand 
atoms can be any unique IDs* For operations in which the older 
of the operands is important, they are ordered by the atom index. 



Figure 13: A sample expression container alow 

If an operator atom for a binary operation contains more 
than two children, the ojxraLion is applied to the first two 
children; then the operation is applied once more to that result 
and the third child, and so on until all the children have been 
used. This allows us to perform multiple operations without an 
undue amount of atom nesting. 

So ultimately tt all boils down ro operands, which are the 
Taw materials" for opera*tons and expressions. There are two 
basic kinds of operands ( aside from expressions, which can also 
serve as operands): constant operands and function operands, A 
constant opera mi is a leaf atom of type kOperandConstant whose 
atom data is a floating-point value; a constant operand atom is 
contained in an atom of type kOperandAtomType. 

A function ofx/mnd returns information about some object, 
most often the current setting of some property of the Ofxrand’.s 
target. For instance, the kOperandMovie Volume operand returns the 
current volume of the target movie (which by default is the movie 
that contains the sprite track). And the kOperandSpriteTrack Variable 
ofXTartd returns the current value of a sfx-cified sprite track 
variable* And the kOperandMouseLocalHLoc operand returns the 
ament horizontal position of the cursor. Most function operands 
take no parameters; when a parameter is required, it s added as a 
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child of the operand atom (in just the same way lhaL parameters 
are added to action atoms). 

The file Movies.h defines constants for over a hundred 
function operands. We can use them to get information about 
the user's internet connection speed, the current day of Lite 
week, the current operating system, the movie rate* a track's 
width and height, a sprite s current image index, and .so forth. 

Draggable Sprites 

Let's consider a real-life example that uses programmable 
actions, the draggable sprite movie shown in Figures i, 2, and 3- 
The basic idea is very’ simple: we want to set the position of the 
sprite to the position of the cursor lor as long as the mouse 
burton is held down over the sprite. There is (as of QuickTime 
3.0) no operand that returns the current state of the mouse 
button, so we'll have to keep track of that slate ourselves, using 
a sprite track variable. We define the ID of that variable like this: 

//define kMouEeStateVarlablell3 2 

'Ihen we need to install three event atoms in the icon sprite atom: 

* When the mouse button is clicked within the sprite image, 
we want to set the value of the mouse-state variable to 1, So 
well add a kActi on SpriteTrackSet Variable action to the sprite's 
kGTEventMouseClick event atom. 

* When the mouse button is released, we want to set the value 
of the mouse-state variable to 0, So well add a 
kActionSpriteTrackSetVariable action to the sprite's 
kQTEventMouseClickEnd event atom. 

* Whenever we receive an idle event, well check to see 
whether the mouse button is dow n or up; if it’s down, we set 
the position of the sprite to the current position of the cursor. 
So well add a conditional action to the sprite's kQTEventldle 
event atom. 

These first two items are easy to do, especially now that we 
have our w ired sprite utilities at hand: 

WiredtJti Is AdriSp r iI uTrackSetVariableAction {theCotltainer, 
mySpriteAtom. 

kQTF.vefiLMouseClick, kMouseStateVariablelU. 1* 0. NULL, 0): 

WIredULils_Add5priteTrack5erV*r[ableAction(theContainer, 
my$priteAtom. 

kQTEventMouseClickEnd. kMquseStateVariablelD, 0, D f NULL. 0]; 

The thud item is a bit trickier, however, since it Involves 
constructing a conditional action and icsing operands to read die 
current mouse position. Let's step though this process carefully. For 
the remainder of this section, well dispense with our standard error 
checking (solely to save some space). In addition, for the moment 
we ll also dispense with the wired sprite utilities, so that we see 
how to do this using just the basic QuickTime APIs. 


Creating a Condition 

Suppose that myEventAtom is the idle event atom inside the 
icon sprite atom. We want to add an “if-then* decision to this 
atom, so we begin by inserting an action atom of type 
kAct ion Case together with a parameter atom that will serve as the 
parent of the conditional atom, which in turn is the parent of the 
expression container and atom list atoms. (See Figure 12 again.) 

CFTlnserrChi 1d( theCdntairier , ayEventAtom, kAct ion, 0* 0. 0, 

NULL, SiayActiDnAtO»): 
myAc Lion = EndianU 3 2_NtoB(kActionCase); 

Q1‘lnaertChiXd[tbeContainer, myActionALota t kWtrichAction. 1. 1, 
s ize q f {myAct ion), 4myAc r i o rj. NULL); 

QTinsertChiId(theContainor, uiyActicnAtom. kActionPatameter, 

1, kFirstParam. 0, NULL. krayParamAtom): 

QTI ns e rtChi 3 d {t heCon t a ine r, my Par amAt om , 

kCon dit ionulAtomTyp e, 0. 1. 0. NULL * SmyCond i l i OfoalAtOm}; 


Specifying the Conditional Expression 

lhe conditional atom contains an expression container 
atom that indicates the condition under which the action list 
contained in live conditional atom is to be executed: 

QFlfteertChiId ftheContainer, myConditiona1Atom, 
kKxpressionContainsrAtomType, J. 1,0. NULL, 
imyExpressionAtoni); 

The expression container atom, in turn, contains an expression. 
In the present case, we want the expression to be: "if the value 
of the variable with ID kMouscStateVariablelD is equal to V\ This 
gets decomposed into an operator atom of type 
kOperatorEqualTo that lias two child atoms (one for each of the 
two operands): 

QTInsertCh i Id (t tieContainer. niyExpr ess i on Atom * 

kOperatorAtomType, kOperatorEqualTo, 1 ♦ 0, NULL, 
firiayQ per at or At on) 

The first child of the operator atom contains the constant 
value 1 So we need to insert an operand atom into the operator 
atom: 

QTInse rtChi Id (rh^Comui net * myOperatorAtom. kap^randArornType. 

0. L. 0. NULL. wnyOperandAtom): 

Then we need to insert an operand type atom of type 
kOperandConstant; in this ease, we can insert the constant value 
as the atom data, like this: 

myConstsntValuo * 1; 

QTInRertChl]d(theContain«r, myOperandAtoan, kOperandConstant, 

1, 1. 0, NULL. &myOperandTypeAtoJn): 

EndianUtils^Float HtoB{frayConstautValue): 
QT5etAtOK0ata(theCont43ner. myOperandTypeAtom, 

Eiaeof(myConstautValue). toyConstantValue); 

Note that we need to make sure that the atom data (of type float) 
is in big-endian format. 

Finally, we need to insert a second operand atom into the 
operator atom. Tit is time, however, die operand is not a constant 
value; rather, it's the value of our sprite track variable. So we 
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insert into the operand atom an operand type atom of type 
kOperandSpriteTrackVariable; this atom then holds a parameter 
atom that specifies which sprite track variable to use. 

QjTlnuettChl Id (thaCotnainer, rayOperatorAtora, kGperandAtomType, 

0, 2 , 0, NULL* &myOperandAtoni): 

QfTInsertChild £ theConta 1 rifir. myOperandAtom, 

kOperandSpriteTrackVariahle, 1, 1, 0* NULL. 
SmyOperandlypeAtoifi); 

njyYariablelD — EndianU32_NtoB(kNoiiseStateVariablelD): 

QTI n e r r. Chi 1 d {the Cont aine r. my Opo rand Type At on* „ 

kAcrlonParameter, 1, 1* sizeof(rnyVariableTU), 

S,myVariab1eTD f NULL); 


Anti so we are finished building the expression container atom. 


Specifying the Conditional Actions 

Now we need to build the action list atom that will lx: 
executed if the expression container atom evaluates to a non¬ 
zero value. We begin by inserting an action list atom into the 
conditional atom; this atom will contain a single child atom, 
which is an action atom of type kActionSpriteTranslate. 

QTinSer tCh i Id (theContainer, my Condi tionalAloiti „ 

kAc l ionL i et AtoraType, 1. 1, 0 * NULL * kmyAc l i onL 1 at Atom); 
QTInsertChildUheContainer, myActionListAtom. kAction, 0. 0. 

0, NULL, imyAciionAtrufi) ; 

myAetion - EndiaoU32_NtoB£kActJonSpriteTransiate); 
QTInsertChild(theContainer, ntyAcliorcAtom, kWhichAction, 1, 1, 
sizeof (tnyActiOn). AmyActioji, NULL) : 

The kActionSpriteTranslate action requires three parameters, 
which are the horizontal and vertical positions to translate to, and a 
Boolean value that indicates whether those values specify an 
absolute or relative translation* We add the fust parameter like this: 

QTTnnertChild (theContainer , myActicnAtoin* kAct1onParaneter, 

CL (shortJkFirstParam* 0, NULL, fonyParamctprAtOB): 
QTlasertChiId £ t boContainer, myParameterAtom. 

kExpressionConta InprAtofuType, K 1, 0. NULL, 
fiimyExpressiojiAtom): 

QTInsertChild(theCoiitaini:r, ittyExpresEionAtom* 

kGperandAtoinType, 0 h l, 0, NULL. ^myOperandAtora); 
QTTnsertChildUheContainer. myOpErandAtom, 

kUperandMouseLocaiHLoc* 1, l t 0 ( NULL, NULL); 


Tine first parameter is an expression container atom that 
contains a function operand, kOperandMouseLocatHLoe, which 
returns the current horizontal position of the mouse. The 
second parameter retrieves the current vertical position of die 
mouse in exactly the same way: 

OTInflertChild(tbeGpntainer, itiyAcLiunAtom, kActianParameter h 
0, (abort) kSecondParanip 0 f NULL, &myPa raise ter At oai); 
QTInsertCHt Id (theCont airier» myParaineterAtoin. 

kKxpr<?E35ionContainarAtoraType. 1. 1, 0. NULL, 

6iny Expression Atom); 

QTI ns e r t Chi Id (t he Con t a 1 n c r * oiyExpressionAtom, 

kOperandAtoinType. 0, I, 0, NULL, &myOperandAtora); 

QTInse rtChiid(theContaine r, myOpe randAtom, 

kOperaodMouselocalVLoc, 1. 1, 0. NULL. NULL): 


The operands kOperand Mo use Local HLoc and 

kOperandMouseLocaIVLoc, like all non-string operands, return a 
floating-point value (of type float). But the kActionSpriteTranslate 
action expects its first two parameters to t>e of type Fixed. It's 
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important u> know that QuickTime automatically converts the 
floating-point values into Fixed values before passing them to 
kActionSpnteTranslate. So we don't need to worry about 
converting the data types here. 

Finally, we add the third parameter like this: 

rayIsAbsolute = true; 

QTInsertCMld ftheGont u 3 nor. myActlouAtoU. kActicmParaiieter. 

0* (shortIkThltdPar&ra, sizeoi(mylsAbsolnrp), 

&myIsAbsolute, NULL); 

So, wv are finished building the action list atom. 

Putting It Aii Together Again 

Listing 14 shows a version of the QTWired_MakeSp rite Draggable 
function. Once again I've omitted most of the error-chec king to 
enhance die readability ol die code. And ihts version uses some 
wired sprite utilities to create the expression container and atom list 
atoms. The file QTWiredSpritesJr.c contains a more complete version 
that has better error checking; in addition, that version contains 
IxHh wired utility calls and basic QuickTime API calls, .So you can 
see how it's done both ways. 


listing 1 4 ; Making a sprite draggable 

pi Wtitd _ MakcS] jri icDragpbk - 


OSErr QTV1 red_MakeSp rif pDm agnblc 

(QTAromContainer iheContainei, QTAtoinID theTD) 

t 

QTAtom mySpriteAtom - 0: 

QTAtom myEventAtom * 0; 

QTAlom myAct ionAtom * D; 

QTAtora utyParamAtom " 0: 

QTAtora ayConri t r i onsl At out . my Express ionAtom. 

myOperatorAtera, rayAc Uon List Atora, myPararae ter Atom; 
short myOp e m rod 1 mlex r 

QTAtonTD myVutiablelD; 

float myConstantValue; 

Boolean rayIsAbsolute; 

OSErt rayErr “ noErr; 

// find ihc sprite atom with the specified TD in the specified container 
aySpriteAtom = OTFindCHUiBylDf tjmCgntainer* 

kPsrentAforalsGontainer, kSpriteAtoraType. thelTi, NULL); 
if (rnySpritRArom = 0) ( 
tayErr = parfmErr; 
goto bail; 

) 

// aild a mouse dick event IuikUlt 

WiredUtils_AddSpriteTrarkSf?t Var UbleActioni rheContainer, 
raySprit ©Atom. kOTEveruNouaeOllcIt. kMotiseStatoVarlablelU. 
1. 0. NULL, 0); 

// add a mouse dick end event handler 

WtredOt Ma_AddSpriteTrackSetVariabl^AeT I em CihcContainer, 
tnySpriteAtom, kQTEventMouEmCliokErid. 
kMoitseStateVariablelD. 0, n. mi. OJ; 

if add an idle event hand Tit 

WicedtJtils AddQTEvciiLAndAetlonAtoraa (theCemtainpr. 

rayfjprireAlom, kUTE vent Idle, kActionCase, AmyArrionAlam); 

// mV\ it parameter a Him i o the kAdJonCase action alum; this will serve as a pi run to 
if hold the expression and action atoms 

WiredUtils_AddActionParara^r erAtom [ ChoCont airier, 

rayActionAtoin. kFirstPoranu 0. NULL. krayFaramAtoin): 

WiredUtilE AddCondUionalAtotiiCtheContainer, rayParamArom, 1, 
AmyCotiditionolAloiiti); 

Wi redlll 11 ;;_Add Exp r as sionCont a in erAtomTypf (t heCotitainer„ 
myConditionalAtora, SrayExpressioiiAtora); 
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Wi redU til s JUldOperatorAtom{theContaine t , royExpressionAtom. 
kOperatorEqualTo, 6myOperator Atom) ; 

myOperandIndex * l; 

niyConstantValue I; 

WiredUtils AddOperandAtom(thfiCantainer, myOperatarAtora* 
kOperandConstant. rayOperandIndex, NULL, myCoDstantValue); 

myQpcrand Index = 2; 

my Variable li) “ kHiniseStateVariabielD; 

WiredUtils_Add Va ria blsOper andAt om{theContaine r, 
myOperatorAtom, myOperandIndex, 0, NULL, 0, 
myVariablelD); 

Wi redllt i I n AddAc r \ onT, I st At ntn (thcCon tainet, 
myCondlti anal Atom, ^myActlonListAtoni}; 

WlredHiiIs^AddAc l i onAt a in [ theContainer, myActionListAtom, 
kAc tionSp riteTranslate, AttyActionAtom); 

// lina parameter; jjcl current mouse position x 

WlredUtils AddAttionParameterAtom(theContainer, 

ttyActionAtom. kFlrfitParani, 0* NULL, &my Faramete rAt on}; 

WiredUt1Is^AddExpressionContainerAtoiiType(theContainer, 
my Pa raffle te rAt om. SmyExpre s sionAtom); 

Wir edUtils_AddOpe r and At ora(th eCo n t ain e r, myEx p r es sionA t om. 
kOperandMouseLocalHLoc, 1, NULL, 0); 

// second parameter set current mouse position y 

Wi redlft 11 s_AddAct ion Parameter A tom (theContainer. 

myAct lonAtom, kSecondParam, 0, NULL, imy Par am ter Atom): 

Wired U t i1 s_Add Ex p r essi onCo nt a in e r At oraT y pe (t heCon t a I n p r, 
myFa ramet e rAt om, AmyExp rea sionAt om): 

Wired Utils Ad dOp e r a ndAt om{theCont a I ft e r , my Ex p res ai on Al om, 
kOperandMoiiseLornlVLoc, L NULL. OJ: 

// third parameter true 

rcylsAbsclute “ true; 

WiredUrils_AddAetionParameterAtom(theContainer, 
myActionAtom, kThirdParam, size of(mylflAbsolute), 
kraylsAbsolute. NULL); 

bail: 

retum(myErr); 

J 

Before we move on, I should mention that 
GTWiredJYlakeSpriteDraggable isn't entirely satisfactory. When 
you dick the cursor on the icon sprite, the sprite is immediately 
moved so that its registration point lies under the hot spot of the 
cursor. This is because the kActionSpriteTranslate action moves 
the registration point of the sprite to the specified location (or 
offsets it by the specified amount, if the translation is relative). 
Ideally, we should he able to “grab" the sprite at any point in its 
image and move it so that the relative positions of the sprite 
image and cursor remaining constant. This is an easy refinement, 
but one that i’ll leave as an exercise for the reader. 

Sprite Button Behaviors 

We've managed to make the icon sprite draggable, but we 
haven’t yet written any code to change the cursor while the icon 
sprite is Ix-ing dragged around. A little browsing in Movies.h will 
reveal the kActionTrackSetCursor action, which lakes one 
parameter (of type GTAtomiDl that specifies the ID of die desired 
cursor IDs less than or equal to 1000 are reserved for use by 
QuickTime. If the ID is 0, Lhcn die default system cursor is used 
if the IT) is greater than 1000, then QuickTime looks in the target 
track's media property atom for an atom of type ersr’ with the 
specified ID; if ii finds dial atom, it uses the atom's data (which 


is assumed Lo be structured just like a Macintosh ‘erst’ resource) 
as the cursor. (On Windows, QuickTime always uses the black- 
and-white versions of the specified cursors.) Movies.h also 
defines these constants to allow us to access some built-in 
cursors (shown in Figure 14); 


enum { 


kQTCii r so r Ope nHand 

= ISIS), 

kQTCursorClascdHand 

“ -19182. 

k QTCu rso r Fo in t in &I land 

- *19181, 

kQTCts rsarRightA r r ov 

** * 19180, 

kQTCur sorLe ftArr ov 

- ■ 19179, 

kQTCu r s o rD ownArr ov 

= *19178, 

kQTCursorUpArrow 

“ ‘19177, 

kQTCiirsorlBeam 

- 19176 


I; 


* « ► 4 w * I 

-19183 -19132 -19181 -19180 -19179 -19178 -19177 -19178 
figure 14: QuickTime's built-in cursors 

So we do in fact know how to add the finishing touches to the 
icon movie: just add art action atom of type 
kActionTrackSetCursor to the appropriate event atoms, 

QuickTime 4 introduced a much simpler and more efficient 
way to attach button-llke characteristics to a sprite, using sprite 
button behaviors. We attach these behaviors to a sprite by 
including an aLom of type kSpriteBehaviorsAtomType in the sprite 
atom. This atony in turn, contains one to three c hild atoms that 
indicate the desired changes that ate to lx- triggered by the state 
of the mouse button and the location of the cursor; 

• To change the sprite’s image on cursor and mouse events, 
we add a child of type kSpritelmageBehaviorAtomType to the 
sprite Ix-haviors atom. 

• To change the appearance of the cursor on cursor and mouse 
events, we add a child of type kSprileCursorBehaviorAtomType 
to the sprite behaviors atom. 

• To change the string that’s displayed in the status area of 
a web browser window, we add a child of type 
kSpriteStatusStrmgsBehaviorAtomType to the sprite 
behaviors atom. 

The atom data in all three of these cases is a structure of 
type 1 QTSpriteButtonBehaviorStruct, defined like this, 

struct QTSpri t cButlonBehaviorSt ruct f 

QTAtomlD no tOve rNotF res sedSta t eID; 

QTAtomlD overNotPressedStatelD; 

QTAtomlD overFressedStatelD: 

QTAt omlD notOve rPtessedStat eID; 

); 

In a sprite image behavior atom, these fields specify die sprite 
image indices to use for the specified stale. In a sprite cursor 
behavior atom, these fields specify the cursor IDs to use. In a 
sprite status strings behavior atom, these fields specify the IDs of 
sprite string variables. If we don't want the current image or 
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cursor or status string lo change when one of these four states 
is entered, we set the appropriate field to -1, 

Listing 15 shows our definition of the 
QTWired_AddCur$orChangeToSprite function, which we use 10 set the 
custom mouseover and mouse-down cursors for the icon sprite. 


Listing 15: Setting a custom cursor for a sprite 

QT>^red_Atld(]urst)K'lun^ToSpritt; 

OSKx r QTWired^ddCur uurChauigeTaSprite 

(QTAtoiwContainer theContainer, QTAtomID thelD) 

[ 

QTAtom taySpriteAtom = 0; 

QTAtom tnyBehaviorAtoin = 0; 

QTSpriteButtcnBehaviorStruct myEehaviarRec; 

OSKrr myErr w paramErr: 

// find die sprite atom with the specified ID in the specified container 
mySpriteAtoin - QTFindChiidBylDftheContainer. 

RParentAtotlsContainer, kSpriteAtomType, theID, NULL); 
if {mySpriteAtom = 0) 
goto ball; 

// insert a new sprite behaviors atom into the sprite . 1 atom 

myErtr = QTlnsor lC hi Id f LheCoiiLainer. itiy Sprite A tom. 

kSpriteBehavioraAtoniTjrpe, 1. I, G. NULL* 
^rayBehaviorAton); 
if [myErr J= noErr) 
goto bail; 

// set tile sprite cursor behavior 

myRohavi orRec .riotOverNotPressedStatoTO * 

Ein3tiariS32JH.oB{ 1); 
inyEehaviorRec. overNotFresaedStatelD = 

EndianS32_NtoE(kQTCursorOperiHand); 
myBehaviorRec.overPressedStatelD * 

EndianS3 2_NtoB(kQTCu r sorClosedHand); 
myBehaviorRet .notOverFtejaaedfltatelD “ EndianS32 .NtoB{-1) ; 


my Err - QTI n s e r i Ch 11 <3 (I heCo n Lainor H my Beha v 1 o r A t om. 

kS p rit e Cu r s or Behavior A tociType, I, I. 
siseof (QTSpriteButtonEehayiorStruct) * 
imyBehaviorRec. NULL); 

bail: 

return(myErr): 

1 

The actions described in a sprite behaviors atom are 
inserted at the front of the Msi of actions associated with a 
particular event; this allows those behaviors to be overridden by 
other actions contained in the sprite’s event atoms. 

Ill leave it as an exercise for the reader to rework the sprite 
controller track code to use sprite behaviors instead of 
kActionSpriteSetlmagelndex actions. 

Conclusion 

In tills article, weVe seen how to use wired actions to 
construct sprite “buttons' 1 that control a linear QuickTime movie; 
wcVc also seen how Lo make a sprite draggable. Both of these 
are pretty simple examples, but they do give us a hint of the 
incredible po%ver waiting to be harnessed. WeVe used only a 
handful of sprite actions, and only two function operands. So 
we’ve got plenty of room to expand our wiring repertoire. In the 
next two articles, well continue investigating wired actions. 

Credits 

Most of die utilities in the file WiredSpriteUtilities.c were 
originally written by Sean Allen; once again, I have taken Lite 
liberty of reworking them to bring the general programming 
style into conformance with the rest of the sample code we’ve 
encountered in this series of articles. MI 
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Cocoa: A New Flavor to 
Mac OS Development 


M ac OS X integrates five separate application runtime 

environments—Carbon, Cocoa, Classic Java, and BSD—into 
one seamless whole, providing developers with many options. 
This article introduces Cocoa, an important development technology used 
by Apple, to develop many of the applications that ship with Mac OS X. 
Cocoa constitutes a new, highly efficient way lor developers to create new 
products for Mac OS X. 


A Brief Overview 

Cocoa is an object-oriented application framework and runtime 
environment—a set of software components used to construct applications 
that run on Mac OS X, Think of Cocoa as a large set of reusable 

application building blocks that can be used as 
delivered or extended for your specific needs. 
Cocoa is based on OpenStep, an object- 
oriented technology that was originally 
introduced in 1987 as NeXTSTEP and has 
been refined through many iterations. 
Consequently, Cocoa is mature technology 
based on a design years ahead of other 
object-oriented frameworks. 

Like any software library, Cocoa has a 
learning curve for newcomers, but it is not 
an overly difficult one and productivity comes 
quickly. The Cocoa framework delivers a great deal of fundamental 
application functionality so you can spend the majority of your energy 
working on application features rather than managing the more tedious 
parts of system interface and user experience implementation. 

The primary implementation language used in Cocoa is Object ive-C a 
superset of ANSI C with specific language features added to allow for 
object-oriented programming. The language extensions in Objective-^ are 
compact and easy to learn. Cocoa applications make extensive use of the 
classes and methods in Cocoa component libraries. However, because of 
Objective-Cs compatibility with ANSI C, they can also make use of core 
functionality contained in traditional C and C++ libraries brought from 
other application environments. 



Features and Development Scope 

Cocoa is a peer to the Carbon and java application development 
environments in Mae OS X, Cocoa supports all Mac OS X application 
service features. For example, Cocoa applications can access the Mac OS X 


native imaging and priming model, multimedia standards QuickTime and 
OpenGL, and Internet and BSD services, too. Localization and 
Internationalization are also well supported by Cocoa, The separation of 
user interface elements from executable code allows you to package your 
applications for different locales easily, with no code changes. All Cocoa 
text drawing utilizes the Uniaxle standards. The text and font systems are 
particularly flexible and allow you to use sophisticated word processing 
features with little effort. 

An important development advantage that Cocoa offers is the capability 
to develop programs quickly anti easily by assembling reusable 
components. With reusable components, developers can not only create 
applications, but also produce: 

* Frameworks (sophisticated library 7 structures) 

* Bundles of executable code and associated resources which can be 
loaded and executed dynamically 

* Collections of custom user-interface objects 

These capabilities support the easy creation and distribution of 
application plug-ins and extensions. 

Tools and Resources 

Apple put die toots for Cocoa development directly into the hands of 
developers by including them in every Mac OS X package on the Mac OS X 
Developer Toots CD. Just install the Developer pkg file and the complete 
Apple tool suite is installed anil ready for use. This installation includes 
the Project Builder Integrated Development Environment, Interface 
Builder—the application for designing and testing user interfaces and 
establishing the connections between objects and actions—as well as ail 
the interface files, debugging and performance tools, and fell online 
documentation. 

Once you have installed the Developer.pkg, open a Finder window and 
you will find the / Developer directory on your system volume. Inside this 
directory', in /Applications , are the Project Builder and Interlace Builder 
applications along with many other tools. In Developer Dc yeumentatic >n 
are folders containing PDF and HTML help and documentation files for 
Cocoa and the developer tools. 

Finally, in /Dcveli)per/Examples are AppKit and /Foundation sample 
code folders with Cocoa applications for you to learn from and even reuse 
for your own project. 

Taking Apart the Technology 

Cocoa Ls comprised of two object-oriented frameworks: Foundation 


Godfrey DiGiorgi is Technology Manager for Development Tools & Cocoa in Apple l Worldwide Developer Relations. He s been associated with Macintosh 
development for more years than he'd care to admit. He can he reached at ramarrm@apphxom. 
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(Tt)undation. framework) and Application Kit (AppKjt,framework). Hie 
Foundation classes provide the low-level objects and functionality that 
form the basis of the Cocoa environment. The classes in Application Kit 
provide the functionality users see in the user Interface, which respond to 
system events such as mouse clicks and key presses. The Application Kit is 
layered directly on Foundation, Here is a brief look at die functionality 
contained in each of these frameworks 

The Fou ndation Framework Is designed to provide a set of basic utility 
classes, introduce consistent conventions for paradigms (such as memory 
management) support (Jnktxle strings, object persistence, and file 
management Foundation includes: 

* the root object class 

* classes representing basic data types such as strings and byte arrays 

* collection classes for storing other objects 

* classes representing system information such as dates and 

* chesses representing communication ports 

Several paradigms are also defined in Foundation to help avoid 
confusion in common situations and introduce consistency across class 
hierarchies. This is done w ith some standard policies, like the one used 
for object ownership (answering questions such as: “Who is responsible 
for disposing of an object?' 1 ), and also with abstract classes which 
enumerate over collections. These paradigms reduce special and 
exceptional cases in code management and allow reuse of die same 
mechanisms with various kinds of objects. All together, these paradigms 
improve development efficiency and productivity. 

The Application Kit framework contaias all die objects needed to 
implement the graphical, event-driven user interface; windows, panels, 
buttoas, menus, scrollers* text fields, etc. The Application Kit handles all 
the details for you as it efficiently draws on the screen* communicates with 
hardware devices and screen buffers, dears areas of the screen before 
draw ing, and clips views. Ihere art- over a hundred classes in the 
Application Kit, so it might seem a steep learning curve, but many of the 
Application Kit classes are support classes that are only used indirectly. 

For a detailed listing of the Ibundation and Application Kit object 
classes, see die documentation in; 

{Developer!!) ocum entationjCocoa/Cocoa lopics. btml 

Object-Oriented Programming 

For traditional Mac programmers, Cix:m development represents a 
paradigm shift—from a procedural to an object-oriented development 
model. Hie “free 51 functionality found in die Foundation and Application 
Kit frameworks helps Mac programmers realize the benefits of Lhis easy, 
natural way to develop applications. 

Object-oriented programming allows the construction of complex 
applications through assembling small, well-tested, reusable modules 
called objects. This provides three simple advantages: 

L Greater reliability by breaking complex implementations into smaller, 
easily testable components. 

2. Easier maintainability 7 due to the small, modular narure of objects, ( This 
small size allows one to fix bugs found in testing more easily.) 

3, Greater productivity through reuse. The ability 1 to use an existing class 
over and over again means less redundant work. When you need to 
extend die functionality of a particular class to meet a specific need, you 


can do so easily through die use of a mechanism called inheritance. You 
only need to code the specific functionality you are adding to a class, the 
rest of the object's behavior is inherited from the preexisting parent class. 
For more information, sec the documentation in- 
IDevetoperjDocu men UitioniCocoajObjectiveClindex. htm l 

Fundamentals of Cocoa Programming 

Cocoa is a rich object-oriented environment. Object-oriented pmgnmiming 
makes heavy use of panerns to simplify- design and implementation of 
complex systems. The three most essential patterns to learn when starting 
are: 

1. Model-View-Cuntroller (MVC) - MVC defines three ty pes of objects in 
an application: model, view, anti controller. Model objects hold data anti 
define the logic that manipulates that data, View objects represent user 
interface dements (a window-, for example). Controller objects act as 
mediators between model objects and view objects. This mediation role 
allows view objects to be free from the programmatic interfaces of models 
and vice-versa. 

2. larger Action - This is part of the mechanism by which user interface 
controls respond to user actions. When a user dicks a user interface 
control, the control sends an action message to the target object. 

3. Delegation - Delegation lets you modify an objects behavior without 
creating a custom subclass. A delegate acts on behalf of another object. 
When a delegate receives a message (from a window, a view, etc ), the 
sender of the message Is allowing the delegate to influence its behavior 
and aid in decision-making (such as: "Should l allow the user to dose 

meT)- 

Cocoa leverages the dynamic binding and object introspection 
capabilities of Qbjective-C and Java by allowing delegate objects to 
implement just the functionality they want to influence. At runtime, the 
delegating objects can query- their delegates to see what methods have 
actually been implemented. This saves you from haring to subclass some 

Continued on page 47 + 


Project Builder 
Tips & Tricks 

• You can use Build Styles instead of duplicate targets 
for many things that would require duplicate targets 
in other environments, 

• All text fields in Project Builder that contain file paths 
support path completion (completion is bound to 
the F5 key by default). 

• Any place where single clicking an item loads that 
item into the built-in editor, double-clicking will open 
the item in a separate window. This includes the 
files list, bookmarks, targets, build results, find 
results, etc. 











New Mac OS X 
Related Releases 


The following software is available from the Download Software 
area of the ADC Member Site at: 
http: i/connect, apple, com / 

• CarbonLib Ud9 SDK 

The latest prerelease version of the CarbonLib L3 SDK fur Mae OS 

• Mac OS USB Driver Development Kit 1.5 

http: ildevetoper. apple, comibardwareiusb/downlnad, him 

m FireWire 2,8.1 Software Developers Kit (SDK) 

http !ideveloper, apple , com/ha rdu a re/FireWirefDeveloperJ nfo. hint l 

#FlreWire$DK 

Developer Documentation 

• O’Reilly and Apple Collaborate on Mac OS X Book Series 

O'Reilly & Associates, has announced plans to publish a series of 
books about Mac OS X development The books in this series have 
been technically reviewed by Apple engineers and are 
recommended by the Apple Developer Connection, The firsL Mac 
OS X titles, Learning Carbon and Learning Cocoa , are available this 
May. In addition, the O'Reilly Network has established the Mac 
DevCenter, a web forum for development news and articles, 

• Apple Technical Publications 

Over thirty new anti updated documents have been added in the 
last month to help developers with successful Mac OS X application 
and peripheral development at: 
http://developer, apple. com /techpu bsf 

TN20I5 - U>cating Application Support Files Under Mac OS X 
TN20I4 - Insights on OpenGL 
TN2013 - The 'plst' Resource 

TN2012 - Building QuickTime Components for Mac OS X 


“Built for Mac OS X” 

Artwork Now Available 

Now that customers have Mac OS X in their hands, 
they'll be looking for great products to run on it. Tell the 
world that your product runs on Mac OS X by displaying 
the “Built for Mac OS X" badge on your product’s 
packaging. The artwork, licensing requirements, and 
usage guidelines are available on the ADC Software 
Licensing web site. 

http://develQpenapple.com/mkt/swt/agreements. 

htmttimacosx 


QA1019 * Can’t attach during two-machine debugging with GDB 
QA1018 * Using AppleScript to seed an email with an attachment 
QA1013 - Mac OS X and root access 


SC - More than thirty new Mac OS X code samples were posted to 
Ehc ADC web site since the last issue. Please visit the URL below for 
a complete list of sample code. 
http://developer, apple, com/sample code! 


Upcoming Seminars 
and Events 

For more information on Apple developer events please 
visit the developer Events page at: 
http. //developer, apple, com/events/ 

Training and Seminars 

• Apple i$ervice& Cocoa Development Classes 

This five-day course provides comprehensive, hands-on training 
using real-world examples. With the skills acquired in this 
course, developers can build full-featured applications using the 
most advanced software environment on Mac OS X. 
http://www. apple, cam/iservices/tecbnicaltrain ingf 
cocoadev.html 

• Programming With Cocoa 

Taught by Aaron Hiliegass at the Big Nerd Ranch, Ashvilte, NC 
and Atlanta, GA. Fire-day classes arc taught on developing 
web-based and Mac OS X applications, 
http: //www. bignerdranch. com/when. him l 

Developer Related Conferences 

* World wide Developers Conference (WWDC) 2001 f 
San Jose. CA 

May 21-25 

Register now for Apple's Worldwide Developers Conference 
2001, which lakes place in San Jem:, California from May 21-25. 
ADC Premier members receive one free pass to the conference. 
For schedules and ocher details check out: 
http://www. apple, com/det eloper/wwdcIOO 1 / 

* Mac I lack Conference. Dearborn , MI 

June 21-23 

Mad lack, in its sixteenth year, remains centered around cutting 
edge software development, Mac! lack’s uniqueness derives from 
the informal fed and the LIVE coding that occurs around-the- 
clock during the conference. 
http://www. machack. com / 
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Continued from page 45 

specific parent class (that has all the default implementations), helping to 
preserve your application s unique class hierarchy. 

These patterns are discussal at length in Inside Cocoa: Object- 
Oriented Programming and the Objective (/-Language and in other pms 
of die Cocoa documentation. 

Another integral pan of Cocoa programming practice is the use of 
Interface Builder Interface Builder is a design tool, allowing you to easily 
define and test a user interface. It is also used with Cocoa to define object 
classes and "wire' 1 the connections of targets and actions. Interface Builder 
creates nib files, which are a static representation of objects and their 
relationships. These nib files are efficiently loaded as needed at runtime. 
Interface Builder is closely tied to the Project Builder IDF lor a smoothly 
integrated development experience. For more information on Interface 
Builder and Project Builder, see the documentation available in: 
/Developer/DocumeniatUm/DevehperTools 
as well as on the Wvh at: 

http://developer.appk\com/tools/projectbuilderl 
http: //developer. apple . cam/taols/ittterfacebu ilderi 

Language Support 

Cocoa Ls implemented in ObjectiveC As a superset of ANSI C with special 
syntax and runtime extensions, Objective^ lets you use object-oriented 
programming techniques while leveraging as much of the use and 
knowledge of standard ANSI C as possible. 

Java can also he used to implement Cocoa applications through the use 
of the Java API versions of the Foundation and Application Kit frameworks. 
See the Foundation and Application Kit reference locations. 

Where to Go for More Information 

* Start with the Cocoa technology web page. It includes News and 
Updates as well as a list of Resources tor Cocoa development 

http://developer, apple, com/cocoa/ 

* Read Inside Cocoa: Object-Oriented IVugromming and the 
Objeaive-C Language. 

http: //developer, apple. com/tecbpuhs/macosx/Cocoa/Cocoa Topics , him l 
http://www I Ja tbra in. com!document at ion/apple/ 

* Sign up for one of Apples development-oriented mail lists, such as 
Cocoa Developer, FrojectBuilder-Lrser, or Java Developer. 

httpd/lists. apple com 

* Check out die mailing lists for Mac OS X and Objective- C developers 
supported by the Omni Group. 

http://www. om nigroup, com/ 

* Lcx>k for the O'Reilly book, Learning Cocoa, due in May. 2001 
http://www. oreifty com/cataiogflea rncocoa 

In Summary 

The demand for Mae OS X applications is huge and Cocoa can help you 
bring new products to market quickly, using the full power of Mae OS X 
development tools and object-oriented methodology to facilitate your work. 

Whatever Mac OS X development path you choose, Apple is eager to 
assist you, For the latest Mac OS X news and information, visit the Apple 
Developer Connection web site at: http://developer.apple.com/macasx 


Did You Know? 

Learning Cocoa—and Mastering It 

o programmers new to Cocoa-Apple's 
powerful object-oriented application 
environment—the road to mastery is a 
challenging yet rewarding one. Although there are 
many new things to learn, once you become 
comfortable with Cocoa, your programming 
productivity will take off. Guaranteed. 

To help you in your Cocoa apprenticeship, Apple 
provides two great sources of technical information* 
The first ts the book Learning Cocoa, published by 
O'Reilly. Written by insiders at Apple Computer, 
Learning Cocoa mixes conceptual overviews with 
hands-on tutorials to give you a crash course in 
Cocoa application development. The idea is that 
learning Cocoa should not be just a matter of reading, 
but doing. Learning Cocoa guides you through the 
creation of several applications, each more complex 
than the one before. By the end of the book, you'll be 
prepared to take on serious application development 
on your own. Look iorLearning Cocoa in technical 
bookstores near you; you can also purchase it direct 
from O'Reilly at: 

http://www.oreilly.com/catalogfleamcocoa/ 

The second source of information on Cocoa is 
Apple's own technical publications, especially its 
Cocoa programming topics. The programming topics 
are a hierarchically organized collection of information 
nodes on such topics as implementing undo, custom 
drawing, and managing text. Each node brings 
together (in an HTML frame set) the conceptual, 
procedural, and reference documentation that 
illuminates a single programming task. In addition to 
documentation, a programming topic includes links to 
example projects, technical notes, and other sources 
of information. If you have the Developer package 
installed, you can access the Cocoa programming 
topics through the Developer Help Center. You can 
also view them on the ADC Developer Documentation 
web site at: lifip://devel(?per,3ppie.com/feclipi/ts/m3COSJ(/C()C03/Cocoa[opics,M!n/ 










ROBOTICS 


By Matthew N. Nathan 


Introduction to Lego Mindstorms Robotics 
for the Mac 


Introduction 

Using the Lego Mindstorms Programmable Brick on your 
Macintosh can he irk ky but definitely worth the effort. The 
purpose of tills article is to introduce the Lego Mindstorms RCX 
Brick and the season;, motors, lights and software associated 
with it as well as to guide you through the procurement, setup 
and installation of your own personal Lego robotics lab. 

Wh at is Lego Robotics? 

Lego Robotics is a system of plastic Lego pieces including 
gears and pulleys, coupled with a small, battery powered lego 
computer: the RCX Programmable Brick, The RCX Brick is about 
the size of two packs of cigarettes laid side by side, is powered 
by six AA batteries and can store up to five programs in separate 
memory locations. The RCX Brick is connected via its input pons 
to small. Lego sensors including touch, light, and temperature 
sensors. Output devices can also be connected to the RCX Brick 
including little lego lights and motors used to power and move 
robots. The Lego rolx>t is programmed using an icon based 
programming environment called Robolab, designed to resemble 
LabVtew by National Instruments. Programs are then compiled 
arid downloaded from the computer to the RCX Brick via an 
infrared tower connected to the computer's serial port. 



Figure l , Ibe Lego RCX ttrick with size comparison 


Once the program is downloaded to the RCX Brick the Lego 
robot is free from the computer. Programs downloaded into the 
RCX Brick will stay in memory even if the RCX Brick is turned 
off. 1 'sing the Robolab programming environment, the RCX Brick 
and the Lego Dacta pieces, including sensors and motors, you 
can create fully autonomous, wireless robots ihat respond in real 
time to environmental stimuli. 

The RCX Brick also has data logging capabilities and can 
record and store sensor data. Data can be uploaded back to your 
Mac later, or, if you maintain line of sight between your RCX 
Brick and your lit tower you can record data points in real time 
on your Mac. The Robolab software has graphing and data 
manipulation tools and also can output sensor date to Excel for 
kill her manipulation. 

A Bkui History of Lego Robotics 

The Lego Mindstorms RCX brick that we enjoy today is the 
product of years of research, tinkering and play by faculty and 
researchers at the MIT Media Laboratory including Seymour 
Papert, Mitchel Res nick, Fred Martin, Rick Borovoy. Robbie Berg 
anti Randy Sargent. As a sponsor of die Media Lab, Lego has firsL 
access to technologies researched and developed by tlie Media 
Lab, I ego s RCX Mindstorms Programmable Brick is a direct 
result of the research at the Media Lab. Thai said, the RCX Bric k 
is completely different from the MIT Programmable Brick’s 
internal construction. Research into smaller bricks, alternative 
programming environments and new sensors continues at the 
Media Lab today. For more information visit the Epistemology 
and Learning Group’s Programmable Brick home page at 
http://eLwww.media.mit.edu/groups/el/projects/programmab1e-brick/. 

Lego Mindstorms was first released to consumers in 1998. 
The original consumer release, called Mindstorms, came with 
software of the same name that is Windows only, At the same 
time, Lego also released ihe Rolxvlab product, essentially a 
Mindstorms kit bundled for schcxib and equipped with the 
Robolab programming environment, a Mac and Windows 
compatible programming tool* 


Matthew N. Nathan is an educator and explorer of the intersection of digital technologies and education. I fe is co founder and chief executive officer 
of Vision Education, an educational ledinolpgy cximpany enabling schools and after school programs to integrate technology effectively into education 
for youth. Matthew is an instructor at The Stoningum Retreat, a lego Robotics and Ix>gi> retreat lor teachers in costal Maine. Me is an experienced lego 
robotics user and educator. Matthew tran tx* reached at nmihcw@visinnedurdiion.com. 
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Getting Started 

Before you can really gel started building and programming 
your Lego rolx)ts you need to buy your materials, which is easy, if 
you know wtiere ro look. In order to program your RCX on tire 
Macintosh you need to buy the Robolab software, at die very legist. 
If you go to any large toy store and buy die consumer packaged 
Lego Mindstorms set you get a RCX Brick, and 1R tower, plastic 
lego pieces and the PC-only Mindstorms programming 
environment. Do not do this. Follow die instructions below to set 
up and run Lego robotics on the Macintosh. 

To buy lego Robotics kits for die Macintosh buy from 
Pitsco-Lego Dacta. Pitsco-Lego Dacia is a subsidiary of the Lego 
Corporation and the only educational distributor for Lego in the 
United States. Pitsco-Lego Dacta has no stores, and their 
produces arc generally not carried in retail outlets. The only way 
to order from them is via die web at www.pitsco-Legodactaxom 
or via telephone at (800) 5624308. Robolab, as an educational 
product is only available from Pitsco-Lego Dacta. 

This author recommends that you buy all your lego 
robotics materials from Pitsco-Lego Dacta including Lego pieces, 
motors, sensors, RCX Bricks and software. Many educational 
bundles of Lego are a better value than their consumer 
counterparts. Educational sets often include more pieces and 
better documentation for the same price. 

To get started using lego robotics you need: one RCX Brick, 
one IR tower/transmitter, die Robolab software, batteries (6 A A 
for the RCX, one 9V for die IR tower), touch and light sensors, 
motors, lamps and wires, and enough Lego dacta pieces, 
including gears and wheels, to build the body of your robot. A 
ballpark figure: to outfit yourself from scratch with a well- 
stocked Lego robotics lab may cost around $400. 


Also, if you have a newer Macintosh without a serial port 
you will need to buy a USB to serial adapter. Pitsco-Lego Dacta 
recommends the Entrega USB to serial adapter and sells it 
through their catalog and web site. Re sure to use Robolab 
version 2.0 with your USB Mac, as earlier versions do not 
support the USB to serial connection, 

If you have already purchased Lego Mindstorms from a 
consumer outlet do not despair. You can buy the Robolab 
software, a Macintosh serial cable and a USB to serial converter 
from Pitsco-Lego Dacta. All the other parts in the Mindstorms kit 
are fully compatible with your Macintosh. 

The RCX Programmable Brick 

The RCX Brick is a small computer with input and output 
ports, a small LCD screen to display important information, an 
infrared transmitter and receiver for communication. It lias a small, 
built-in speaker and tan play individual MIDI notes (no chords) or 
certain pre-programmed sounds. The RCX Brick is powered by six 
AA batteries but can also connect to an AC adapter. 

The Lhree inpul ports on the RCX Brick are labeled 1, 2, and 
3. Each can connect to an external sensor. Currently the 
following sensors are available through Pitsco-Lego Dacta: touch 
sensors, light sensors, angle sensors, rotation sensors, and 
temperature sensors. These sensors are manufactured by Lego 
are connected to the RCX via wires ending in 2x2 Lego stud 
plates. Tlie Lego studs (the little bumps tin the top of a piece of 
Lego that lock Into other pieces when you build.) on the sensors 
contain metalirized connecters that conduct power and data 
between the RCX Brick and connected sensors. Third party 
sensors are also available through Pitsco-Lego Dacta including 
humidity, pit and voltage. 
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Xcaret Pro Expansion Bay CDRW Drives 

• Bootable! * Hot Swappable * Fast Backup or File Transfer ] 

* Toast™ 4 Software - Protective MCE Carrying Case 
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PowerBook S3 99 & 2000 (Lombard & Pismo) 

prunes and Disc Burner Compatible! 

Infernal Hard Drive Upgrades for PowerBooks 

■ The BEST Internal Hard Drive Upgrade Kits for your PowerBook! 
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Focused on 

Mac Technical Positions 

There is a better idea when it comes to finding 
a job: mactechjobs.com... the only career site 
dedicated to providing career opportunities 
for technical professionals focused on the Mac. 
Programmers, developers, network 
administrators, web developers, 
content creators and more. 



Resume Posting Private - If you are currently working, you may post you resume anonymously. 


Automated Job Search Agent'- Fill out the job search criteria, and every day, the Agent searches 
for job postings matching your specific criteria. 

Automatic Notification - When the agent finds a job that matches your archive, it automatically 
sends you an email notification. 

We Get YOU Job Offers Quickly - Because we Specialize in only Technical Macintosh positions, 

we can put your resume in front of more relevant employers than any other 

Internet employment resource. , 



Focused Job Search - Target your search by keywords, top 5 skills, 
salary requirement required. 


Exceptional Quality Control - We offer a quality resource 
that is IT specific. All job postings are reviewed by our online editors 
for their appropriateness and industry relevancy. 


Aggressive Marketing & Promotion - a direct marketing 
campaign, to promote the site to the largest and most prestigious 
employers in the industry, is underway. 

































You can ,stack multiple sensors to one sensor input port 
(he. by stacking their 2x2 stud plates on the same inpul port 
on the RCX Brick). For example, you could stack two touch 
sensors, touch! and tou<:h2, onto port 1 on the RCX Brick, 
However for programming purposes they are 
indistinguishable. If either touch 1 or touch2 is pressed the 
RCX will read “touch at port 1/' 



Figure 2 , Lego touch sensor ami lamp 

The output ports on the RCX Bric k are labeled A, B and 
C. The only output devices currently available are motors 
and lamps. Motors connect to gears, pulleys and axels and 
arc use to make the Lego robots move. The lamps are small 
LEDs embedded in 2x1 Lego bricks. Both motors and lamps 
have metalacized contacts and connect to the RCX Brick via 
Lego wires like the sensors, 



Figure X Detail of a Lego wire, Note the metalkized stuck. 

The Lego sensors are all fairly accurate and are adequate 
for most robotics projects. Plus, they are inexpensive (from 
$11 to $27,50) and very easy to use. However, for those of 
you interested in more professional sensors, DCP, a 
manufacturer of scientific probes has created, with Pitsco- 
Lego Dacta, a DC? sensor to Lego RCX adapter. The DCP 
sensors are very expensive compared to the Lego sensors. 
They cost between $55 and $195 per sensor and to use any 
of the DCP sensors the user must also buy the Lego to DCP 
sensor adapter for $55- 

The IR transmitter and receiver on the RCX Brick can 
communicate with the IR tower, other RCX Bricks or the Lego 
RCX IR remote control. Unfortunately, the RCX Brick uses a 
custom IR modulation protocol that makes ii very difficult to 
communicate with other lit devices such as Palms, and IR 
equipped Macs. 

The IR transmitter and receiver on the RCX Brick can 
operate in low and high power modes. The maximum range 


Fight Boredom 

Let’s lace it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model-View-Controller 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code" 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete 1 resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com R»0*W*E*R*S 

Development 

P.O. Box 929, Grantham, Nil 03753 • (603) 863-0945 • FAX 863-3857 
howersdev@uol .mm • hUp;//members .aol.com/bowerstlcv 
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THURSBY SOFTWARE has the 
perfect file share solution to 
meet your needs. 



The ideal solution for Hie small 
office where Macs & PCs need 
to share files. 



The fast, easy way to share 
files and printers between 
PCs and Macintosh systems. 


DAVE? 


It’s totally cool! 

How cool would it be for your Macs and PCs to become best friends? To share text 
and graphics files and postscript printers across a network with no harriers. Get 
DAVE, the “totally coot* 1 file share solution from Thursby Software. DAVE installs 
on your Mac. It's fast, secure and simple to use... period, tor sharing with Windows 
95/98/Me/NT/2000 and soon, for Mac OS X. 

Download a FREE EVALUATION today. 





Jt 


THURSBY 

Software 


f ile 6lar& folk#* 

www.thursby.com 

© 2001 Thun by Schwarc Syjttuft Iftf. 


Macworld 



Achieve true NFS connectivity 
between your Mac and 
UNIX systems. 



Windows users can access 
files on any Mac workstation 
or AppleShare server. 
















Macworld 

Conference & Expo 


Conference Programs & Workshops 

July 17-20, 2001 

Exposition 

July 18-20, 2001 

Jacob K. Javits Convention Center 

New York City 


Register Online Today! 

www.macworldexpo.com 

Call Toll Free 1-800-645-EXP0 


Owned ittJ U**ml<* 

#IDC 

WORLD EXPO X 

©2001 IDG World Eapo. 

All rights reserved All other trade¬ 
marks contained herein are the 
property of lha respective owners. 



Register by June 18, 2001 to SAVE $150 
on a Macworld Conference & Expo SUPER PASS! 
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www.macworldexpo.com 

with your Prionfp§|§e: A-WITC3 


by June 18,2001 to take advantage of Special Savings! 


Our long-standing dedication to technology development merits 
Macworld Conference & Expo as the ultimate venue for all levels 
of Mac users, professionals, enthusiasts and the Mac-curious 
to gather and experience the excellence of Mac technology! 

The most important Macworld Conference yet! 


Workshops 


Macworld/Users Conference Program 


Tuesday, July 17, 2001 

The week begins with 13 astounding, full-day workshops 
that provide in-depth training on key products and 
technologies. You can find full workshop descriptions at 
www.macwortdexpo.com. 

Macworld/Pro Conference Program 

Wednesday, July 18 - Friday, July 20, 2001 

Macworld/Pro offers the most sophisticated training 
available on Macintosh for the advanced users and 
skilled professionals. Six distinctive tracks include: 

* Macintosh Networking and Communications 

* Mac OS X in Depth 

* Professional Publishing 

* Application Spotlight: FileMaker Pro 

* The Mac Manager Track 

* Digital Media 


Wednesday, July 18 - Friday, July 20, 2001 

The Macworid/Users Conference continues to be one 
of the best educational values anywhere, offering over 
80 educational sessions on a variety of exciting topics 
presented by industry experts! Mac users and enthusi¬ 
asts can learn about Mac OS X — your first taste!, 
Desktop Movies, Digital Photography, Tips about your 
Favorite Applications, Digital Imaging and much more! 

Many Macworld/Users sessions can be combined as 
curricuiums for 

* Creative Professionals • Small Business Owners 

* Musicians * Educators 

After great success last summer, 
MacBeqinnings returns to New York! 

Open to ALL registered attendees! 


World-Class Exposition! 

Wednesday, July 18 - Friday, July 20, 2001 

Excel in life with the knowledge and solutions, 
at Macworld Conference & Expo — the wj 
comprehensive Macintosh OS event! 

♦ Visit over 400 exhibiting companies 

♦ Discover thousands of new products and 

♦ Test-drive the latest Mac OS X applications 

♦ Participate in live demonstrations 

♦ Evaluate the latest technological innovatioi 

A 

Brand New for New York! 



MacBeginnings 

Wednesday, July 18 - Friday, July 20,2001 

Visit www.macworldexpo.com tor session times and 
descriptions. 



The hottest up-and-coming companies and developers in the Mac industry will be on display as you 
stroll down the Special Interest Boulevard and visit MacTech Central. 

Visit www.macworldexpo.com tor the most up-to-date exhibitor list. 


Fl$g$tiip Sponsors 

Macworld MaCWOrld.com MacCentral.c^m 








for IR communication is approximately 40 1 but this author 
has not had reliable success beaming IR commands from 
lower to RCX beyond a range of 4'. 

Also, direct sunlight and fluorescent lighting can 
interfere with infrared communication. If you are unable to 
gel a reliable signal between vour IR tower and your Mac, or 
if you know your cables and port settings are correct but you 
continue to gel error messages, lighting may be your 
problem, A simple solution to light problems is to construct 
a table tent: fold a 8" x 10" piece of paper in half lengthwise 
and let it rest over the IK tower and the RCX Brick when you 
are downloading programs or uploading data. 

The IR remote can turn the RCX on and off, select and 
run programs and turn power to Individual output ports on 
and off. The remote control is particularly useful in situations 
where the “run 1 button on the RCX is hard to reach due to 
Lego construction around ii. 

Building with Lego 

Besides the RCX Brick, IK tower and software, you will 
need plastic Lego pieces before you can get started building 
robots. The Lego KCX Brick is compatible with all Lego sets 
and pieces. The one exception to this rule is Lego Du pin 
pieces. Lego Duplo is the extra-large Lego pieces designed 
for very young children. Duplo is not compatible with other 
Lego because of its size; it's just too big. 



Figure 4. Traditional Lego bricks and [dates 


Though older Lego is compatible with the RCX Brick, 
you will need specialized Lego dacla pieces in order to 
construct most robots, line specialty pieces include a variety 
of gears, cam shafts, pulleys, axles, beams, bushings, 
connector pegs, and other pieces specially designed for more 
sophisticated Lego robotic construction. Your old bricks, 
plates and other pieces a re perfectly usable in your ne w Legi > 
robots but you will most likely need to buy more Lego to 
have success building new robots. 
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WIBU-KEY 


The ONE-KEY solution 


One hardware fits all 
interfaces 


One software for all 
programming languages, 
operating systems and 
networks 


One license, any WIBU-KEY - 
choose from USB, LPT, ADB, 
RS232, PCMCIA, MECPC9800 


WIBU-KEY is ready for Mac OS X! 

WlBU-SYSltMS has been o member of USB Implementors Forum since 19V7 As the ftrsl copy protection produtl certified by tbs 
LfSB-IF, lli# WIBU-BOX/U sixxcssftjlly completed al USB Compliance tests and is offici-ofly included in the USI1 Integrators Usl 




























Have Your Data 
Access Challenges 
Got You In A KNOT ? 



Bring Data To Your Macintosh from Any Database 
With OpenLink's Universal Data Access Driver Suite 


OpenLinks HIGH PERFORMANCE Universal Data Access Drivers facilitate 
the rapid integration of legacy, current, and future data sources with 


Macintosh based desktop productivity tools, intemet/intranet development 


& publishing environments, and corporate eBusiness solutions, 


Exploit the freedom, choice and cost-effectiveness that universal data 


access technology brings to your organization. 
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FEATURES; 

© Compatible and Usable across broad array 
of ODBC compliant applications 

© B i -d i rec tion af scroi I able cursor support 
© O DBG 3.5 and JDBC 2 .0 Compl i ant 
© Blistering Performance* 


Download A Free, Fully Functional Non-Expiring Copy 
from our Web Site Today: www.openlinksw.com 
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Figure 6. fc^odoctes, 6wrf>w.gj, connector pegs “ 
and other specialty pieces 
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seven times faster 


free demo 
www.onyx-tech.com 


Find memory errors automatically in source 
Code Fragment Support 
Leak Detection 

*3j%P Toolbox Parameter Checking 



Lego Sensors 

A variety of sensors can connect to the RCX Brick. 
Standard Lego sensors include touch sensors, temperature 
sensors, light sensors, angle sensors, and rotation sensors. 
Touch sensors arc simple button switches with two states: in 
and out. The temperature sensor is quite accurate within a 
reasonable range. It is made of plastic so be careful not to 
expose it 10 extremely high temperatures or the sensor will 
melt, The light sensor senses reflected light through a small 
aperture and reads values 1 - 99, The light sensor reading 
does not correspond to any traditional measure (watts, 
lumens, candles). Readings arc measured in Lego light units 
(IXUs). Angle sensors and rotation sensors both connect to 
Lego axles and measure the change in angle from a zero 
degrees and the number of rotations of the axle, respectively 



Figure Z lego temperature sensor and light sensor 


Robot ab Programming 
P ilot Programming 

Programs written on your Macintosh using the Robolab 
programming environment control the RCX Brick, Robolab is 
an icon-based programming tool and. as such, has no written 
programming language. Robolab has two separate 
programming interfaces: Pilot and Inventor Each interface is 
divided into four levels. At each level the user has more 
programming options than the level before until finally, at 
level four, the user has access to the complete functionality 
of the Robolab programming environment. You may wish to 
look at programs written in levels one through three to get a 
feel for the programming but when you sit down to do your 
own programming this author recommends using level four. 

To create a Pilot program click on an icon on screen to 
get a pop-up menu of all the programming options for that 
port, device or conditional. Choose the command you wish 
from the options and it automatically gets put into your Pilot 
Robolab program. 
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“Without a doubt, the Premiere Resource Editor 

for the Mac OS ... A wealth of time-saving tools.” /M 

- Mac User Magazine Eddy Awards 

£I A distinct improvement over Apple s ResEdit” 

- MacTech Magazine 

"j Every Mac OS developer should own a copy of Resorcerer ” 

- Leonard Rosenthol , Aladdin Systems 

“Without Resorcerer, our localization efforts would look like a ^ 

Tower of Babel. Don't do product without it!” 

Greg Galanas, CEO and President, Metrowerks 

“Resorcerer s data template system is amazing. ” 

— Bill Goodman, author of Smaller Installer and Compact Pro 

*Resorcerer Rocks! Buy it, you will NOT regret it. 77 

— Joe Zabkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and effort 
— MacUser review 

“The template that disassembles ‘PICT's is awesome!” A 

- Bill Steinberg, author of Pyro! and. PBTooh Amt 

“Resorcerer proved indisperisible in its own creation! n 

- Doug McKenna, author of Resorcerer 




Version 2.0 



* Very fast, HFS browser for viewing file tree of all volumes 

* Extensibility for new Re sorcerer Apprentices (CFM plug-ins) 

* New AppleScript Dictionary facte’) Apprentice Editor 

* Mac OS 8 Appearance Manager-savvy Control Editor 

* PowerPlant text traits and menu command support 
■ Complete AIFF sound file disassembly template 

* Big-* little-, and even mixed-endian template parsing 

* Auto-backup during file saves; folder attribute editing 

* Ships with PowerPC native, fat, and 68K versions 


New 

in 


Requires System 7.0 or greater. 
1.5MB RAM, CD-ROM 


Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it’s easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-based, design and opera tinn 
All file information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rez-like scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, ApplcEvcnt, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, 'icth’s, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PO's, or Visa/MC 
Taxes: Colorado customers only 


source ID or type changes easily i 
files from simple Rez-like scripts 


Extras (call, fax, or email us): 


wan, joa, ujl email un / 

COD, FedEx, UPS Blue/Red, 


Internationa] Shipping 


MATHE M/ESTI-IETICS, INC, 
PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 


re sorcere r@mathemaes thetics. com 


To order by credit card, or to get the latest news, bugfixes, updates, and apprentices, visit our website, 


www.mathemaesthetics.com 













Up tbs pwtrtfAppteStript 
witb Main Imt’s SsripteH 


For professionals and novices 
Webmasters and solution providers 



Figure 8. Simple Pilot level J program.. I his program turns on 
a motor connected to jx>rt A for four seconds and then ends . 
Note the pop-up output menu. 


No matter what your experience, 
Scripter makes it easier! 

BEGINNER AT SCRIPTING? 

• Unique command-builders help you team to 
assemble commands 

• Built-in tools for experimenting 

• Shortcuts to speed scripting 

EXPERIENCED WITH APPLESCRIPT? 

• Unmatched single-step interactive debugging 

• Watch and modify global and local variables 
while stepping 

• Debug messages sent to script applications 

• Includes ScriptBase to integrate scripting scenarios 


ScWpter received Mac Week's 5-diamond rating - Twice! 
"Scrlpter's virtuoso display of AppleScripting sowy and 
debugging wizardry make it the best environment weVe 
found for teaming or creating AppleScript scripts 
—Mac Week 


Mate Appl&Swipt and your 
appteateos verb far y«it 



Main Event 
PO Box 21470 
Washington, DC 20009 
Teh 202-298-9595 
Sales: 800-616-8320 
info^maine vent com 
www.maineventcom 


The Pilot progranming interface is very easy. It is used in 
schools with students as young as eight years old. The Pilot 
interface gives the user basic input and output functions using 
timers, touch sensors, light sensors, lights and motors. If you wish 
to use other sensors (temperature, for example) you will have to 
write your program using the Inventor programming interface. 

Another key difference between the Pilot and Inventor 
programming interfaces Incomes apparent when we look at the 
logic structures. All Pilot programs execute sequentially. Using 
the Pilot interface the user cannot create if-else loops, 
subroutines, or run tasks in parallel Also, the looping structures 
available in the Pilot interface are quite limited: repeat the entire 
program once or repeal the entire program forever After 
becoming familiar with the Pilot interface it is suggested that you 
continue on to Inventor to continue your programming. 





Figure 9- One step of a Pilot level 4 program. This program turns 
art a motor rotating dackunse connected to pod A at a power kvd 
of Jive, a lamp connected to pod B at a pouter level of three and a 
motor connected to jx/rt Q rotating cmnterclockudse at a power 
lad of three . Then, when the touch sensor connected to jxtri f is 
pushed in. the program continues to step J. Note tlx> hoping 
structures jnpup window to repeat once or rejx>atforever. 
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A New System is Coming 



netOctopus is ready. Are you? 


Mac OS X is coming. It’s right around the corner. You may 
be going through your preparation checklist right now. 
wondering if you have enough time: 

✓ Inventory all installed software 

✓ Check software versions 

✓ Check hard disks and memory on all computers 

✓ Identify hardware upgrade needs 

✓ Print summary reports 


With netOctopus, you can do all of that with a few mouse 
clicks. Then, when OS X arrives, get the new version of 
netOctopus, and use it to distribute all of your new software 
throughout your network seamlessly. 

Timbuktu Pro, the # 1 remote control and file 
transfer software for the Mac, integrates seam¬ 
lessly into netOctopus, for even greater net- 
Ti mbuktu work support! 



With netOctopus, you would practically be ready for OS X today. 
Without netOctopus, you may be running out of time. 



www.netoctopus.com 


<D Netopia, Inc, 2001 All rights reserved. Photo by William Swank 








Lnventor Programming 

The Inventor interface looks quite different from 
the Pilot interface. It uses floating palettes (tools, 
functions, help, etc.) and much less is done for you in 
building your programs. Like the Pilot interface, the 
Inventor interface is divided up into four levels, with 
each level offering increased functionality and 
programming capabilities. 

Though it is more sophisticated than the Pilot 
interface, Inventor still uses icons to represent inputs, 
outputs, conditionals and other logic structures. 
Programs are written by dragging commands 
(represented by icons on the Functions palette) inLo 
the program construction window. Once tlic icons are 
assembled they must be connected to one another 
using the connecting wire tool from the tools palette. 

Inventor allows you to create if-else loops based on 
sensor data (i.e, if the temperature sensor reads above 
a certain temperature then do X, else do Y), internal 
counters, timers and variables. You can create counting 
loops and go to statements all iconicly, Go to 
statements are represented as “jumps" and “lands/ 
Think of it like this: the jump command jumps the 
program's sequential execution from the jump 
statement to a land statement somewhere else in the 
program before or after the jump. Effectively you can 





“Their incredibly kind stafffocus on getting the 
job done as well as their customer's feelings. 
All experiences should be so pleasant.” 

-Nril Ttdom, Publisher 
Mat Tbit Mugodw 

7 Good Reasons to Choose DriveSavers 

1. Fastest, most successful data recovery 
service available 

2. Retrieve recovered data instantly with 
DATAF-XPRESS™ over high speed 
secured Internet lines. 

3. Authorized to perform Data Recovery 
on all Apple computers and hard drives. 

4. 24-hour, onsite, and weekend services. 

5. Advanced, ptopnetaiy recovery techniques 

6. Featured by CNN, 

BBC, Forbes. Also 
in Mac World, 

Mac Addict, 

Popular Mechanics, 
and many others, 

7. Federal and Slate 
Contracts 

(CSA, CMAS). since im 


‘We Can Save It!” 

INTL 415-382-2000 
www.df ivesovers. com 


DriveSavers - Your Data Recovery Solution! 


jjtfOOO LWM&WHS. INC 400 Ml MAWN KEYS &LVD, NCA4MD. CA ?494V_lNTL 41 5 - 382 2^. j 


use jump commands to jump backwards in your 
program Lo repeat a set of instructions until a condition 
is met. You can also use jumps and lands to jump 
forward out of a loop when a condition is met and 
continue with your program's execution. 



Figure 10. A simple Inventor level 4 program. Note 
floating functions and tools palettes. 

Inventor also allows you to record sensor data and 
counters in variables represented as color-coded 
“containers/ You may perform simple calculations with 
container data (addition, subtraction, multiplication and 
division) and use container data in conditionals. For 
example, if you build a merry-go-round and you want 
it go around four times before stopping to give your 
patrons a fair ride, you can connect a rotation sensor to 
the main axle of the merry-go-round and store the 
number of rotations from the sensor in a container. You 
can then use that container as a part of a loop to run 
the merry-go-round. The program would keep Lite 
motor running, and the merry-go-round going until the 
value of the container is greater than four then it would 
stop the motor. 

Another very cool feature of the Inventor 
programming interface is the ability to program RCX to 
RCX communication. RCX Bricks can communicate to 
one another via the 1R port on the RCX. They must 
have line of sight to communicate and be within range, 
RCX Bricks can send simple “1 see you” commands or 
they can beam container data back and forth. 
However, if you have multiple RCX Bricks talking to 
each other, at this point there is no way to distinguish 
in your programming “send a message to RCX 1 but 
not RCX 2/ 
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You think your kids are safe on the Net. 

Think again... 



ContentBarrier. The new Parental Control 
solution for your Macintosh. 



Block offensive in atonal 

Sim the internet 



You don't let your kills read just anything, tin yrm? MMI, when 
they surf iIk- Ihuttk i, they can see whatever they want, unless 
you're thereto watch over their shoulders. Willi CcdrntBaniei; 
die internet Ls a safer place for your children 
Content Harrier sets up a protective wall around your 
computer Its pre defined categories let you choose what 
yon don’t want your children to see. and yon can also 
create your own custom categories, Inappropriate web 
sites are blocked, shielding your children from things they 
are too young for. 

(bntentRarrier blocks adult web sites, sites with subjects 
not 111 for children, and even blocks chats when predatory 
language is used. It blocks all offensive content coming 
from the Internet. 


Licences avatlabte 


ContentBarrier works with multiple users; if you I we several 
children, you can set Meroii enterhg corresponding to their 
age or maturity. You can choose whether they have access lo 
newsgroups, entail, or whether tlicy can download ffbw You 
can set the program to ki them only use the I niemet at certain 
times ami on specific day's. The program out even send you 
email automatically, wlien certain events occur. 

(billetiilianicr keeps a compkle log of all web sites visited, 
whether blocked or not. This allows you lo have a full record 
of exactly what your children are doing on the Inutnet You 
can also lake an inventory of your children's computer, and 
find all pictures, movies, music files ml web pages. 
CofiittiiBarrier makes die Internet a safer place for your 
children. 


,%m&+ 


www.intego.com 




ContentBarrier is fully compatible with Intcgo's acclaimed NetBarrier and VirusBarrier 
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www.macosradio.net 

(a Mardun Software Ltd, company) 



<$><$> <£><3><2>O0 


Figure 1L Inventor level 4 with all palettes ofxm: Functions, 
Modifiers, Music , Reset t Wait For Structures, Container and 
RCX to RCX Communication. 


•Talk radio about the Mac, 
only on the Internet. 

• No more surfing to 100 
different sites to get your 
MacOS news. 

•Interesting guests from 
companies you care about 
and sources you listen to. 


ALL MAC 
ALL THE TIME. 


For more information about Internet 
radio, QuickTime Streaming Servers 
and how you can develop the power 
of MacOS X Server for media 
streaming today, e-mail 
sales@macosradio.net 
or call 

573-443-0301 


ROBOIAB PROGRAMMING - INVESTIGATOR 

The Investigator programming interface is used 
exclusively for data gathering using die RCX Brick and is 
new in Robolab 2.0. Essentially, using the Investigator 
interface die user am program the RCX Brick to record 
sensor data from input ports thaL can lx: logged or 
immediately uploaded back lo the Macintosh, 
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Figure 12. Investigator Level t program, this 
program will record a data point from the light sensor 
connected to port t every second until it has recorded 
10 data points. Note the popup wait for window. 


In Investigator the user can control the number of 
data points the RCX records as well as the frequency 
that points are recorded. Like tile Pilot and Inventor 
interlaces, Investigator is divided into five levels with 
new functionality introduced at each. At lower 
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is a simple- story. 
Write your code once. 

Run it (without change) 



here, here, here, here, here, here & here! 


Demos and information from our web site: 

http://www.truebasic.com 

TRUE BASIC INC • Founded by the (ttVCnforS of BASIC 

PO BOX 5428 • WEST LEBANON NH 03784-5428 • 800 436-2111 * 802 296-2711 
















Inventor levels the user can only control the data 
logging functions of the RCX Brick. However, at higher 
levels the user has access to some of the most 
sophisticated commands available in Robolab. 
Investigator level five allows the user to perform 
significant data manipulation using one-dimensional 
arrays and a variety of calculation functions. 
Investigator level five also allows for more robust RCX 
to RCX communication. The user can turn other RCX 
Bricks on and off, run or stop programs on the other 
RCX and change the program number (1 - 5) that is 
being run by the other RCX Brick. 

Lego Robots and Resources 

Perhaps the biggest challenge in creating working 
Lego robots is having the mechanical engineering 
knowledge to take a handful of motors, axles and 
gears and fit them together in a way ilial accomplishes 
the robotic construction goal you have in mind. There 
are several resources to help with Lego building. 

Print Resources 

One resource that any experienced Lego builder 
has at his or her disposal is Lego’s own construction 


blueprints and diagrams. These blueprints provide 
step-by-step building instructions for creating specific 
mad tines or robots. The blueprints outline all the 
pieces needed for a given construction as well as the 
program needed to make the construction run. 
Different Lego Robotic kits come with different kits 
and the user can also buy blueprints on their own. 
Even older Lego blueprints that do not include the RCX 
Brick can be redesigned by a creative engineer to 
incorporate motors, lamps, sensors and the RCX Brick. 

Another extremely useful resource available to the 
novice Lego engineer is the Lego Construe! a pedia, The 
Constructapedia contains some step by step building 
blueprints hut the most valuable pan of the 
Construtapedia are the Lego cliches: small pictures oi 
particularly useful mini-constructions. Rather than 
provide an entire robot's construction, this section of the 
Constructapedia shows details of larger constructions, 
parts of the whole that can be replicated for a variety of 
uses. Useful constructions ranging from rack and pinion 
steering systems to cantilevered wheels and casters are 
all depicted in the Constructapedia, 
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Several books are also currently available from third 
parly publishers about Lego robotics that are worth 
mentioning. Dave Baum/s Definitive Guide to Lego 
Windstorms (Technology Tn Action) and Extreme 
MindsLorm.s: an Advanced Guide to Lego Mindstorms . 

both by Dave Baum are very good books about Lego 
robotic construction and alternative programming 
languages. Dave Baum is the creator of NQC (Not Quite 
C) and his first book is very NQC-centric, Extreme 
Windstorms was released in October 2000 and contains 
more Information about NQC, pbForth and LegoS, all 
alternative programming environments for the KCX 
Brick. Extreme Windstorms also includes information 
about making your own sensors at home to expand the 
capabilities of the RCX, The Unofficial Guide to Lego 
Mindstorms Robots , by Jonathan Knudsen provides a 
good overview of alternative programming 
environments, home built sensors and how to build 
sturdy Lego constructions. The IInofficiaI Guide is 
published by O'Reilly and is a good technical reference. 

Online: Resources 

In addition to the print materials available about 
Lego robotics, there is an extensive collection of Lego 
robotics resources online. Legomindstorms.com, the 
official Lego Mindstorms site, has an extensive image 
bank documenting robots created by users around the 
globe. The web site also has robots built by Lego’s 
own expert builders. Blueprints are not provided for 
the robots, but they can be studied to learn new design 
concepts or Lu get new building ideas. 

Lugnet.com (Lego Users Group) is the largest 
online community of Lego enthusiasts with active 
bulletin boards, Lego auctions and pages and pages of 
content. Only a portion of the site is devoted to Lego 
robotics, per se, but their Lego robotics pages are 
excellent. LugneL.com is an excellent place to comb for 
answers to technical questions, share innovation or just 
talk w T ith other like-minded Lego robotics. LugneL.com 
also has extensive links to other Lego sites on the web. 
It is an excellent jumping off point for Lego robotics 
web browsing, in general. 

Conclusion 

Lego robotics on the Macintosh is extremely exciting. 
The capabilities of the RCX will only increase with time. 
Future developments in the RCX will include increased 
miniaturization of the RCX technology, introduction of 
new sensors and output devices and increased 
communication capabilities via 111 and the Internet. KJ 
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Come to the Mac OS Experts 


Red Rock Software specializes in Macintosh software development. 
Our team of senior engineers averages over 10 years of development 
experience on the Macintosh platform. Our experience and expertise 
has gained us the trust of companies like Apple Computer, Iomega 
Corporation and Sorenson Media. 

Let our experts make your product compatible with Mac Os X. 

• Aqua Interface Implementation 

• Os X Carbon Porting 

• Os X Native Cocoa Application Development 
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We have the best engineers around. 
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Delivering Innovative Engineering Solutions 
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When something unusual incuts, it takes 
thoughtful advisois to interpret meaning and 
impact. Moving your software up to Mac OS X? 
It’s not your usual migration— so you neat an 
expert guide who knows how to get you upgraded 
will tout getting lost As the Midwest’s largest 
Apple developer, Parallel is llte OS X transition 
expert. We ll give uncommon insight to your 
application planning, development, and 
successful migration. 

Fly by our White Papa; Mac OS X Migration at 
www.paralld.coni 

Call us at 877-PARAIIRL 
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Without sufficient resources or the right expertise, your project is at risk of shipping late. 
Atimi guarantees reliable and timely Macintosh software development. You get to market 
on schedule—and to the satisfaction of both you and your customer. With a wide array 
of technical expertise, Atimi offers a full range of services: 

Classic Mac OS to Mac 05 X application porting (Carbon and Cocoa) I Windows to 
Mac OS application porting Application development Driver development 
(printer, PostScript, USB, Firewire, etc.) Networking development (wireless and wireline) 

Call 604.813.1319 or visit us at www.atimi.com. 

Look for our booth at WWDC! 
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Macintosh software development. On-time. 












" - • m u . „ , ^ , _- „ . 


* f? :?*»•« r :::: J r j * ** I ««* 

- - * ,. - . . . 

tm- % « «, «*J r i!5 'a " ■ 

Kt'tifv?!it ?*••■ ** 

i* +. u. i m L ... _ . . 

















Eat your vegetables. 

□ Exercise every day. 

8! Port to Mac OS X. 

□ Call your mom. 

All of these are good for you. j 
We can make one of them easy, j 


Since 1989, The Omni Group has worked with ihe technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That’s been our business for years. No matter what kind of product you have, we can get it up under 
OS X, fast: 

• Real games: We ported id's Doom and Quake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's FrameMaker to NEXTSTEP and Sun's Concurrence to OpenStep/Solaris. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

• Serious drivers: We ported idfx’s Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote QmniWeb, the only native OS X web browser, and OmniPDF, the native .Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it. too. 


The Omni Group 



2707 Northeast Blakeley Street sales@omnigroup.com 

Seattle, Washington 98105-3118 800.31S.OMNI x201 

www.omnigroup.com/consultlng 206.523.4152 x201 
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MAC OS X 


By Andrew Stone 


Just Ship It! 


Building Electronic and CD software 
distributions for Mac OS X 

Now thm you have written, debugged, IxHn tested and 
finished your online documentation for your whizzv new Mac 
OS X application, it’s time u> make it available lo rhc world! Hack 
in the old days of Mac OS 9 and earlier, developers had a 
selection of package making tools, including the almost dc facto 
Stufllt™, For Mac OS X however, there is no need to rely on third 
party vendors to create your installation packages: Apple has 
provided some powerful disk image creation utilities that come 
with the base release of Mac OS X. This article will reach you 
how to use those tools by hand* give you an example of a totally 
automated packaging shell script, and go into the finer points, 
such as including a background image in your distribution 
folder. These same tools can create yonr muster for CD 
replication as well 

Tin: Macintosh Way 

A quick review of some of the online developer discussion 
groups will reveal the huge amount of emotion developers have 
over the right way to distribute software packages. Open source 
and tree ware folks swear by gnutar, but that is a problematic 
solution lx'cause Apple no longer includes gnutar in the base 
distribution. And, Ix'Cause of legal issues surrounding the GNU 
projects *Cupyleft\ Apple did not build in an unpacking 
mechanism for the industry standard gnutar ball. So, for now, 
forget simply packing up your distribution with gnutar ezf, 
although you get the highest level of compression and smallest 
resulting downloads, 

Apple has come up with a great packaging solution, 
although the resulting downloads are somewhat bulkier— disk 
images are optimized for decompression speed, not minimum 
compression size. The emphasis has become on how easy a 
distribution is to unpack and how to reduce the number of 
steps a user has to take to get the software installed. If you 
have visited the iTools site, and peeked into the Mac OS X 
software download folder, you II see a bunch of 


AFPNAMK.dmg files — “disk image" files. The same technology 
that Apple' pioneered for distributing firmware upgrades, the 
self-mounting disk image, .sink has evolved to be a great way 
for developers to distribute their wares. 

The user simply double-clicks the down loaded ,dmg file, 
and the Copy Disk utility launches, anti automatically mounts 
the download as a the disk image. During the mounting. 
Copy Disk verifies the integrity of the image by matching the 
checksum with the encoded checksum. The user then sees 
your distribution folder w ith your application in it. They can 
try out your app from the disk image if they want, or they 
can just copy it Lo their applications folder. And that is the 
entire installation process. 

Because the OS X bundle architecture encourages 
developers to place all the related files of an application inside 
the application wrapper, your application can he anywhere on 
the user's computer and still function correctly, This is an ideal 
situation because we should never force users to do anything a 
certain way* esj)cdally not for some arcane technical reason. Tf 
your installation requires frameworks that must l>e installed in 
a certain location, you should consider either including them 
inside the appwrapper. or perhaps using scripts that install the 
software For the user in the correct location. Rule I is Lo make 
your installation so idiot proof that even adults can use it. 

The Tools 

You use the command line tools, hdiutil and hclid, to create, 
mount, eject and compress your disk image. A complete guide to 
tile usage of these programs is included in Lite online manual 
pages. Type “man hdiutil" to see all the options. Let's walk over 
this process. FI I use APPNAMF as a stand in for whatever your 
application is called in the following scl of instructions. 

1. Launch Terminal.app from /Applieations/Lftilities 

2. become “roQt\ aka super user 

mdo s 

then provide an adiiunstrator password, probably your own 
login password if you are set up to administer your machine. 


Andrew Stone. CEO of Slone Design, www.stone.com, h;is been ending in Cocoa as an Independent software developer for over 13 years 
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You need to be rtxu because you will be creating and mounting 
disk partitions which requires root access. A user cannot sudo to root 
if they are not a member of the admin group. To allow a user to 
become an administrator, choose the "Users 11 module from System 
Preferences Show All" pane. Select the user, and dick "Edit User”. 
Make sure that tire “Allow user to administer this machine 11 switch is 
checked, and click OK. 

By default, Mat: OS X ships without a root account for security 
reasons. The traditional way of becoming substitute user, su, wall 
fail. To add a root user, launch NetlnfoManager from 
/Appl ications/Uti titles. Ch(xxse Domain->Security->Authenticate..., 
and provide die admin password for your computer. Choose 
Domait»5ecurity->Enable Root User. You will be asked to provide 
a non-trivia] password, don’t forget it! 

3. Change directory to where you want to build your disk image — 
preferably a disk with a lot of free space! 

ed /Volumes/BIG/distribution 

4. Create die scratch, uncompressed disk image to which you will 
copy your application. You should !>e liberal with the size you 
allocate with die -megabytes flag. Having too much extra free 
space will not affect the final compressed size, but having too little 
will annoy you when you cannot quite copy all of your application 
onto die image. Doubling die size dial your application requires 
seems to always work. The -layout Hag can be NONE for net- 
distributed application, but you must use the SPUD (Single 
Partition UDTF) option for a CD-R master. If you are planning on 
using the same image for Net distribution as CD distribution, then 
use SPUD here. The -zeroI mage tells bdkilil to w rite zeros to all 
sectors in the image file, which seems like a good idea to me. 

hdiui.il cteate ‘APPNAME scraich.drug* megabytes 10 -layout 
NONE -zeroImage 


5. Alert the operating system of the existence of this new disk using 
lidid — but don't mount the disk in Finder. 

Mid AFFMME-scratch.drag -nonount 

After entering this command, the system will reply with die 
allocated device now connected to the disk image: 

/dev/diskl 

You'll now use this information in the next step when you 
initialize the disk image. It’s always of the font /dcv/disk<N>, 
starting with 1. 

6. Create an HFS file system with the name you want Finder to 
display, using the standard 4K blocksize, -h 4096. If you used - 
layout NONE above: 

newfs_hfs -v AFFNANE -w -b 40% /dev/diskl 

If you used -layout SPUD above, you need to initialize the second 
partition which contains the actual AppleJ-JFS disk, since the first one 
has the partition map on it: 

newfsjifs -v APPNAME -w b 4096 /dev/disklsZ 

7- Eject the image, again replacing disk! with whatever was returned 
in step 5. above. 

Ml util eject diskl 

8. Now, do a complete mount of the disk so that it appears in Finder: 

hdid AFPNAME-scratch.dtng; 

>/dev/diskl 

At tills point, die disk image appears as the icon of a removable 
drive entitled the name you gave to die -v option in step 6. Now, copy 
your application and readme files to the new disk. Set the permissions 
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Funnel Web lv ’ Will Show You How. 
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as needed — later in thus article, you 11 learn how to change liie folders 
background image and set custom folder icons, 

9. Eject the disk 

hdiutil eject disk! 

NOTT-: If disk won't eject because "its busy", you may have to 
logout and login or even roix>oL 

10, Make die annpressed, net distributable, disk image: 

hdiutil convert 'APPNAME-scratch .drag* -format t|DC0 o 

■APPNAHE-200104 06‘ 

The -format option is UDCO (UDIF compressed image) for net 
distributions, and UOTO (DVD/CD-R master image) for your Cl) 
master image Hie correct file extension will lie added by hdiutil. i 
think it Is wise to indirde a cLite in the name of your distribution, so 
that users an quickly and correctly tell whetlicT they need to 
download a newer version or not. 

Automating The Prixess 

Ken Case, a founder of OmniGimip, www-OmniGroupioni, avated 
PackigeAppliaition. Tliis handy script not only creates the cliskjmage, 
but preprocesses your application to remove extraneous Hies and 
symbols, makes a copy of the release, installs Ikimcwoiks inside of the 
application, copies the app to the image, compresses the image, and 
creates an equivalent tarball for a more traditional (and somewhat 
sniiilla) l ’XIX distribution. Tliis is a zsh script♦ s <> save it to 
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Package Application and make tile appropriate changes to PUBLIC 
path, and then make the file exen liable: 

chraod 755 PackageApplicatiori 

Now, you an package an application with, e.g.: 

stidc -u root PackageApplication AtTNAMR 

Sudo allows you to execute commands as another user — you 
are prompted for a password — provide your own. See man sudo for 
more information on this handy utility. 

I leres the script: 


*tybinAs>fi -l r 
# 

* Copyright xm-mn Omni Development, [rac.Afl rights icscrwd 

# 

* ^Header Ao\vork/^rtiR:cA.VS/l>itioKiTiuip/>cripls/ntt1^gcAnpti^Hi(ir,v 1.27 
2001/03/14 20:19:28 kc Esp $ 

™LlC=/bscr s/Shared 

APPNAME-S1 

if [ "SAPPNAME" - I: then 
echo “Usage: 50 app-uame" 
exit 1 
fi 

if [ "SSOnOJlSKR" - : then 

SUIXUISER - "$USER“ 
fi 

INSTALLE0PR0D0CTS=$PtiELIC/$SUD0_USER/Ins La\ledProdoctfi 
PACKAGED I R“$PUBLIC/$SUD0_USER/ Rei ease/SAPFNAHE 

cd /tmp 

echo "Copying Hilts from $ INSTALLED PRODUCTS to SPACKAGEDIR 

vc ho " iNote: 'his assumes thiti n 1 ! •! JiN.'iTAUiWDFRODUCTS 

is needed tar 5APPNAME. If not. remove iwcl rebuild,) 

(rd $ lMSTAU.EDPRDDUCTS ; chmod *R u+x .: tar cf - ..) | tm -rf 
I p $PACKAC SPACKAGEDIR; tar xpf - 

it egtep v 4 tar: Unable to net file nid/gid of .* <Uo such 
lie or directory)*) 
cd SPACKAGEDIR 
echo “Cleaning, up release" 
dtmod R u+V.go W.a+rX . 
chcwn -R root,admin . 2>/dev/null 
- (ka rid of l hose < \S kflovers ,. 

find . TUiwi* CVS -type rf -exec rm rf U prune 

find . name 'J*‘ type f exec rm II -prune 
l sct> dun t nml framework doniromtaiiun .lihI luuikrxand tloriopcratan gel 
tlxne liy duwnfouftng rkm separately 

find . name ‘*.minx H exec hr (I \: prune 

find . name 'Documentation" exec mi rf U \: prune 

find . -name "Headers* exec rm tt if V; prune 

find . name “PrivateMeaders' exec mi ri 11 prune 

echo Ta ripping debugger symbol table entries from Kech-G 

files" 

find * type f print | xurgn file | grep Mach-G | awk -F: 

* I print $JI' | while read file 
do 

echo M $file" 
strip S Sfiie 
chrBod a lx Sfile 
done 

if [ ~$AITNAMF7 ' “OmiifVeh*" ]; Then 

echo "Moving plugins In to SAFPNAMR plugins'" 
m ‘ .plugin SAPPNAHE.app/Coni eni s/Pluglnfl 
fi 

echo “Moving frameworks Into SAPFNAME frameworks" 

Bikriir SAP?MA!fE. app/Contents/Frameworks 

inv ‘.framework $APPKAME,app/Contents/Frameworks 

if | d OmniGroupCranbCatcher.app 1: then 

echo "Moving Otr i i f-roLpCraahCarrher into 3APPNAKE resources"' 
mv Omu iCruu jkJr oshCa i c h e r. app 5APPNAME, app /Contents/Resources 
ti 

echo "Setting up launcher" 

mv $APPNAME.app /Contents/MacOS/1 *.ISAPFNAME 

rw Launcher SAPPMAME *app/Content g/M acOS/SAPPNAMF 
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P Scripting Saves Time - InstallerMaker 
provides full scriptability for all features. 
Automating the build process saves rime 
and helps ensure the integrity of your installer. 


Trialware in Minutes - Creating trial ware is a 
breeze with Installer Maker. With just a few * 
clicks, and no extra coding, you can create 
trialware that is e-commerce ready. 


Update in a Flash - Easily build intelligent 
,T diff" files in installers to create small updaters for quick 
online distribution. From one simple installer, you can 
update 68k, PowerPC or FAT applications. 


More Details Online - There's a lot more 
InstallcrMaker can do for you. Get all the 
info at www.aladdinsys.com. 
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i Get It Together 
with Instaleillllaker 


When Time Is Money, Get It Done Fast! 

Build Smaller Installers - With Stufflt InsrallerMaker, you'll build installers 
faster than ever before! Compress your installers an average of 15% smaller 
using the power of the Stufflt Engine". Smaller installers download faster, 
provide added space on CDs and servers, and increase network bandwidth. 

Quickly Create Demoware - Easily turn your application into a polished 
demo. Just set the number of days for the demo to be active, paste in the 
graphics, and you're done! 

Archive Freshening - Automatically update your installer project file; 
eliminate repeated searches for modified files. 
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echo “Total size of $PWD” 
du -s * 

echo "Bunding tar file” 

PACKAGEDATE-'da te *+ftY■■*d"' 

TARBALLJJAME=" $APFMAME -$PACKAGEDATE .tar.gz" 

TARMLL="$FUELIC/ $TARBALL_NAME" 
tar czf $TAREALL SAPPNAME.app 
echo "Building Disk Copy image” 

LABELNAME-** $APPNAME ■ SPAOtAGEDATE" 

SCRATCHTMGE =t1 $PUBLIC/ $ ( LABETHAMEI Temp - $$. ding” 

DI5KC0PY IMAGE”" $TARBALL: r: r. ding" 

* Create the image 

echo ** Creating scratch image.,." 
rro -f $SCRATCH!MAGE 

hdiutii create SSCRATCHIMGE -megabytes 10 -layout NONE - 
zerolmage 

* Create a Alev/disk device from the image 
drive=* hdid -nomount $SCRATCHIMAGE* 

* Create a new filesystem on the disk device 

newfs_Ms v “$(APPNAME)" b 4096 /dev/r$idrive:t) 

* Remount ihe tfisk 

echo “ Image formatted, ejecting $1 drive)../’ 

hdiutii eject $[driveI 

echo ** Mounting SSCRATCHIHAGE*.." 

drive"'hdid $ SCRATCHIMAGE" 

echo ** Searching for $ (drive]..." 

while [ “$M0UNTP01NT" = ] 

do 

M0UMT0INT='df -1 | grep Sdrive | awk ’(print $61*' 
done 

echo “ Found $drive at $MQUNTFOINT" 

* Unpack the tuhall into the mounted filesystem 
echo “ Copying application,,," 

(cd SMOUNTPOINT itL gnu tar xzpf $TARiiALL] 

* Eject the disk 

echo " Ejecting. *, ’* 
hdiutii eject $idrive I 

* Convert die image to a IJDIF compressed image 
echo * Compressing...* 

hdiutii convert format UnCO $SCRATCH I MAGS o $UUSKCOPY IMAGE; r) 


Felt Tip fTh, 

Sound Studio \!D 

Record and Edit Audio 

with a sound editor designed for the Mac. 
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Sound Studio features 
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Felt Tip Software, G07 Keely Place, Philadelphia PA 19128-2126, USA 


gzip 9 < $DISKCOPYTMAGE > $DISKC0PYIMAGE,gz 

# Remove the temporary image 

echo ” Removing scratch image" 
rm -f 5SCRATCHIMAGE 

# 

frAil done! List die refilling packages to the tfcset 
# 

Is -Ig STARBALL $DISKCOPYIMAGK $DISKCQFYIMAGE,gz 

Ghitevg Fancy 

The automated process is great if you a re happy with a standard 
folder with your application m it. You can use the utility ditto to copy 
files that have resource forks with them — or you can just drag and 
drop them onto the disk image. Since Finder Ids you associate images 
with folders, let's take advantage! I have not yet figured out how to 
automate the process of adding a background folder image—because 
the image MUST point to within the new file hierarchy on your disk 
image — and tins has to be done with Finder. If you preset it on a 
folder which you then copy to your disk, the copied folder will point 
hack to the original image, which will noi Ire on foe end user's disk! 

The Finder stores information alxiuL a folder in a file named 
,DS_Store — normally you cannot see files that begin with a 7, Use 
the -a option to Is lo see this hie: 

Is -la 

^Ew-rw-rw- I andrew admin 22604 Mar 26 17:28 .DS_Store 
To set die background image of a folder. 

1. in Finder, select the folder, and set the view to Icon mode 

2, Choose View > Show View Options... to bring up the View 
Options window, 

5. Select the “Window” pane. You must have the Finder window in 
“Icon” mode to access this feature, 

1 Uncheck die TJse Global View Preferences” switch 

5. Select die “Picture” option, and click “Select..7 

6, Navigate to an image included within your new disk image's hie 
hierarchy and dick “Choose” 



Figure 1 . Fora fmfessiortai touch t include an mstmetm image in 
the top to /folder 
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You can also set a custom icon for any folder — these do 
copy fine via Finder or ditto, since they are stored in the folder. 
Our artist created them in Mac OS 9 with iconFactory, a plugin 
for Photoshop http://www.iconfactory.com. In Mac OS X, you cart 
copy/paste folder icons like this: 

L in Finder, select the folder which has the icon you like 

2. Cbtxtse File -> Show Info 

3. Click on the icon in the upper left hand comer, a lx)x will show 
that it Ls selected 

4. Choose Edit -> Copy 

5. Navigate to the destination folder on which you want die icon ui 
appear 

6. Click on the Info window’s icon 

7. Chfxise Edit -> Paste 


(eeo 


ri 

LmiDiq 


Info: Stone Studio 


Stone Studio 


Show: General Information 



Kind: Folder 

Size: 39.2 MS on disk (34,159,930 bytes) 
Where: Install Stone Studio/ 

Created: Tue, Mar 6, 2001, 5:19 PM 
Modified: Fri, Apr 6. 2001, 4:19 PM 


Figure 2 /hWm aw have their aum sjkvial icon. 



You’re Toast 

Making a CD master image is very similar to making a net 
distribution, with a few changes in the creation of the disk 
partition, in the initializing of the new file system, and in the 
compression phase (steps 4,, 6, and 10, from The Tools 
above). When we create the disk image, well use the SPUD 
layout and make it large enough to hold all those quicklime 
movies and demo files! 

hdiuTil create *APPNAME-ucratch,dmg* megabyits 160 
layout SPUD -zeroImage 

The process continues the same until we initialize the new 
disk — we want to intialize the second partition: 

netffs.hfs v APFNAME -¥ -b 4096 /dev/diskls2 

The process continues the same until we get to the very 
end when we make a raw disk image for use by Toast or 
other cd recording software: 

hdiutil convert ‘APPHAME scratch,dag* formal IJDTQ o 
1 APFMAME_CD_2 0QG-Q4-06 * 

Yon are ready to burn your golden master and you’ll be 
.shipping CDs within days. 

Conclusion 

The disk image format is a simple and surefire way to 
distribute your software clceironieally, and the same tools let 
you create CD master images. 

Thanks to Jim Kareley and Eric Peyton of Apple 
Computer, Inc., who assisted me in understanding these 
tools, Byron Man, principle engineer on the Disk I mages 
project, and Ken Case for Pack age Ap pi ic a tk m. BO 
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I’d rather create clocks than invoices. 

If I wanted to keep books all day, I’d have been an accountant. 



MYOB software is the simplest, most powerful, most complete solution 
for managing my company on the Mac, from the day to day to the 
bottom line, 

: • ::: •*•**.' ii ::::■ ;; t *;• si :: ;jj ‘*• •::»;*•;*‘;; j j * " 

Antique frames. Quartz movements. That’s my business. 

MYOB software works for me. 








PROGRAMMER'S 

CHALLENGE 


by Bob Boomtra , Westford, MA 


Basic Klondike 

ril admit it. I got into programming in an unusual way. 
Predating the web by a Few (!) years, I didn't start with HTML or 
Peri. Nor, unlike some of my colleagues, did I start with a PC with 
toggle .switches where the keyboard input should have been and 
with LED output instead of a video port No, l actually started by 
reverse engineering machine code programs, and then discovering 
assembly language, and only later high level languages like 
FORTRAN and COBOL, 

But .somehow, through all that, 1 missed BASIC as a language, 
only discovering it much later, and never developing much of an 
attraction for it. But BASIC hasn't gone away, it is still alive and 
kicking as a modem object-oriented development environment, 
ibis month we're going to have some fun with BASIC, courtesy of 
the folks at REAL Software. 

WeVe been using QxleWarriur for the Challenge for some 
time now, starting with C, expanding to C++, anti allowing Pascal 
even though Metrowerks (or should I say Motorola) has 
deprecated that language. We’ve accepted Java solutions, although 
with some restrictions. But weVe never even considered BASIC - 
lifter all T BASIC is a beginner's language, not used by serious 
programmers, right? Well, maybe not. 

It turns out that there are real applications being written 
in BASIC. I discovered one, MacDynDNS, when I was forced 
to change DSL providers to one that didn't grant static IP 
addresses. So, when I was contacted by the folks at REAL 
Software about holding a REALhasic Challenge, I decided to 
experiment with their environment. 

We're not in the business of endorsing products, but a little 
experimentation demonstrates that REALhasic is pretty cool. It 
converts BASIC into a fiilly object oriented language, and the 
environment does a surprising amount of the work required to create 
an application for you. They provide a nice tutorial that helps you 
quickly start using the environment. .And they offer a free 30-day 
demo (see http://www.roattxisic.com/), which we're going to take 
advantage of with dlls month's Challenge. 

The prototype for the code you should write Ls well, there 
isn't one. Your task is to build a REALhasic application that lets me 
play the card game Klondike. Klondike is a solitaire card game, the 
ot^ject of which is to build up ;tll 52 cards onto four foundation piles 
in ascending order, by suit, from the Ace to die King. As a reference 
implementation for what constitutes legal play, Fm using the 
shareware game by Mike Casteel available at www.casteel.oig. The 
requirements? You need to display a graphical representation of die 
game - die cards in the tableau, the four foundation piles, die deck, 
and the Lop three cards revealed from Lite deck. You need to support 
playing cards and stacks of cards by dragging them from one pile to 
another. You should highlight the destination when a card is dragged 


to a jxisidon where it can legally be played and, of course, allow 
only legal moves to lx* made. You need to provide multiple levels of 
Undo and Redo. You should provide menu items to start a new r 
game, to replay the previous game, to save die game state, and to 
resume playing a previously saved game. Your application should be 
user friendly, warning the user, for example, when s/he Is about to 
quit an unfinished game. You should provide preference controls 
tliat allow me to turn over one card at a time instead of the usual 
three and control whether scoring is displayed. 

How will I .score tills Challenge? This Challenge will lx a 
departure from our usual reliance on execution time and program 
size. Apart from the requirement that the solution lx* “correct*, the 
winner will be chosen based on features, usability, and elegance. As 
options, you might automatically detea when the game has been 
won. You can optionally play music. You can add attractive features 
that you think might gain my favor. The Challenge prize will be 
divided Isetween the overall winners) and the best scoring entry 
from a contestant dial has not won the Challenge recently. 

And I'd appreciate hearing from you on what you think of this 
experiment in language and in scoring. If it proves to lx popular, 
perhaps well try some more experiments like this one. 

Three Months Acio Winner 

Eight people entered the February Trilite Challenge, a two- 
player game resembling Tic-Tac-Toe, but with the restriction that 
each player can occupy at most three positions on the board. 
Congratulations to Jonny Taylor for taking first place, narrowly 
Ideating out the entry from Challenge points leader Ernst Munter 
Both Jonny and Ernst realized that the player making the first move 
has a guaranteed win, and each won all of their games when playing 
first, Jonny, however, fust only to Ernst while playing second, while 
Ernst's entry earned a draw against a third player after 40000 moves 
in addition to losing to Jonny. Congratulations also to Cords Clark, 
for submitting the best placing entry by someone who has not 
previously won a Challenge, 

Of the eight entries, one crashed during play, so I eliminated 
that one from the tournament. I then ran a tournament with the 
remaining seven entries, with each playing die other entries twice, 
Once playing first and once playing second. AH of the games Ux)k 
IxLween 8 moves and 18 moves to determine a winner, excepting 
those against contestant Randy Boring, who excelled in staving off 
defeat. Kandy's entry forced ties with three contestants, including 
Ernst, using a bane-force approach tliat also rook top honors for 
using die most execution time, 

Jonny’s code is sparsely commented and tough to read. The 
first time it is called, his enLry calculates a number of tables of 
winning positions that are then used on all subsequent calls. The 
code uses a data structure that allocates 4 bits for each piece on 
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the hoard for each player. It uses Lhe remaining bits of a long 
word to encode which player is to move next and 3 bits of 
information about how far the position is from a forced win. 
There is space in the data structure for a visit count, apparently 
intended for use by unimplemented logic to prune the search 
algorithm. Jonny stretched the rules a hit by using some assembly 
axle inirinsk's, but performance turned out not be a discriminator, 
and 1 decided to lei this indiscretion slide. 

Since the play against Kandy Boring's entry proved to lie 
decisive, it is worthwhile to examine his games against the top two 
entries. In the board positions below, the positions occupied by 
one player are labeled "O" and those of the other player W X", with 
lower case letters used to indicate the position that will disappear 
next. The draw between Kandy (O) and Ernst (X) looped around a 
sequence of eight positions: 

1:0 mo A: dtQ b:-Xt> 7 : m 8: (*- 

XiO Wo Wd j«- -X- - 5 0 x-o x-o 

-ck -a — -O* -<K ffi -Ot -<SC 

Tlie game between Randy (O) and Jonny (X) took 30 moves, 
and is provided l>ebw. Note that the decisive move was made by 
"X in move 28, w here he occupied a position that formed a line 
with his opponent's piece that was about to disappear. 

1:0- 2:0- 3:00 4: GKO 5:cfl» 7:-X0 Bi ->D 

— -X- X -X- -x- "3ir Ck- (OX 

— — -0- 30- >D 

9:0k- !G:0-X I1:CH< 12: 0-X D:u X L4:^x Hj-Gk 16: XD- 
0-X OX o-X (ifa Xt -X- -X- -x- 

X> :<-0 o QO (X) Oto Ob 



1-88-USB USB US 

-or- (1-888-728-7287) 


Worldwide Distributors of USB 
and Pi reWire Parts, 
Peripherals and Accessories 

lley Developers: 

http://www. ushfir.uf £ .com/developers.html 

1-877-4 HOTWIRe 

-or- 1-B77-446-8947 

fireMJCreStuff 


!7:XD- IG:X£>- I9:to0 20: xoO 2Ux-0 22:-0 23:-o 24: X-o 
Ck- OX O-X OX OCX cik <X -0- 

tx- tK- x- x- x- xx- xo m 

25:XD- 26:XOX 27:XOX 28: xOX 30:-ox 

-o- -0- 0- OX OK OX 

#0 -to -e — -X 

The table below lists, for each of the solutions submitted, 
total execution time, the number of wins and lies achieved, and 
the total numlxT of points earned (100 for each win, 30 for each 
tie, minus 1 point for each millisecond of execution time). It also 
lists the code size, data size, and programming language for each 
entry. As usual, the number in parentheses alter the entrants 
name Is the total number of Challenge points earned in all 
Challenges prior to tills one. 


Name 

Data 

Points 

Lang 

Time 

(psecs) 

Wins 

Ties 

Code 

Jonny Taylor (.36) 
691 

10969 

C++ 

0.39 

11 

0 

28308 

Ernst Munter (711) 
422 

10350 

C++ 

2.00 

10 

1 

4908 

Rob Shearer (55) 

976K 

5497 

C++ 

0.56 

3 

1 

1148 

Con is Clark 

88 

3000 

C++ 

0.74 

3 

0 

1236 

Willeke Rieken (132) 3000 
378 C 

1.81 

3 

0 

1444 

Joseph Stront (10) 

m 

1434 

C++ 

182.37 

1 

1 

956 

Randy Boring (135) 
130 

-9037 

C++ 

16588.42 

6 

3 

10008 

c w, 

1740 

Crash 

C 

0.00 

0 

0 

1240 


Top Contestants 

Listed here are the Top Contestants for the Programmers 
Challenge, including everyone who has accumulated 20 or more 
points dining the past two years. I’ve changed the formal a bit this 
month. The numbers l>dow include points awarded over the 24 
most recent contests, including points earned by this months 
entrants, the number of wins over the past 24 months, and the total 
number of career Challenge points. 


Rank 

Name 

Points 
(24 mo) 

Wins 
(24 mo) 

Total 

Points 

1, 

Munter. Ernst 

291 

n 

721 

X 

Rieken, Willeke 

87 

3 

134 

3. 

Saxton, Tom 

76 

2 

185 

4. 

Maurer, Sebastian 

68 

2 

108 

5- 

Taylor, Jonathan 

56 

2 

56 

6. 

Shearer, Rob 

55 

i 

62 

7. 

Boring, Randy 

52 

i 

135 

8 r 

Wihlhorg, CLaes 

29 

i 

29 
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_ Marketing Rule no. 1 _ 

MAKE YOUR PRODUCT EASIER TO BUY, YOU'LL SELL MORE OF IT. 


Vou may have developed the best software in the world, but if nobody 
knows about it, or ton find it, you won't sell muth of it. With eSellerote, 
your application literally sells itself. Providing your customers with the power 
of instant gratification. And providing you with an opportunity 
of nearly limitless potential, w w w. e s e 11 e r a t e . n e t 6 $ 0 I 6 T □ t 6 
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... and toe Top Contestants Looking for a Recent Win 

In order to give some recognition to other participants in the 
Challenge, we also list die liigli scores for contestants who have 
accumulated points without taking first place in a Challenge during 
die past two years. Listed here are all of those contestants who have 
accumulated 6 or more points during die past two years. 


RankName Points Rank Name Points 


9. 

Downs, Andrew 

12 

17. 

Strout, Joe 

10 

10. 

Jones, Dennis 

12 

18. 

Hala, Ladtslav 

7 

11. 

Day, Mark 

10 

19. 

Miller, Mike 

7 

12. 

Duga, Brady 

10 

20. 

Nicolle, Ludovlc 

7 

13. 

Fazekas, Miklos 

10 

21. 

SchoLsman, Jan 

7 

14. 

Flowers, Sue 

10 

22. 

Widyatama, Yudlii 

7 

15. 

SadeLsky, Gregory 

10 

23. 

Heithcock, JG 

6 

1(5. 

Selengut, Jared 

To 





There are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that l use. The points you can win are: 


1st place 

2nd place 

3rd place 

4th place 

5th place 

finding bug 

suggesting Challenge 


20 points 
10 points 
7 points 
4 points 
2 points 
2 points 
2 points 


Here is Jenny’s winning Trilite solution: 


Trilitexp 
Copyright © 200 T 
Joirny Taylor 

//include "Trilite*h" 


Ptr gMentoty = QL; 

unsigned abort’gWhiteToMovel, *gWhiteTcMove2, ■ gWhitefoHoveB, 
*gWhiteToMove4; 

//define ASSERT (CONDITION) //assert(CONDmON) 

^define X_MASK OxCCCCCC 
^define YJ4ASK 0x333333 
ffdefine XYJ1ASK XJ1ASK + Y_MASK 

//define &LACKMITSTWIN 0x01 

//define WTMFLAGMASK OxEO 
//define WTR5FLAGMA5K OxFO 
define WTM4ELAGMASK OxQOEB 
//define WTM3FLAGMASK QxQQFC 
//define WTM2FLAGHA5K OxOOFE 
//define WTMlFLAGMASK OxDDFF 

//define BUCK3P0S 20 
//define BLACK2P0S 16 
//define BLACK1P0S 12 
//define WHTTE3F0S B 
//define WHITE2F03 4 
//define WHITE 1F0S 0 

r Jhcse two flags me used to mdkate positions where one or both colours hive a line 
WHFTEHASUNE is also used when both players have ;i Line. If rirlicr tlig is readied when 


tmring positions backwards, that route should lx- ignored, since you could never play 
onwards from a winning position. BLACKHASL1NL is flagged differently so il can be 
identified as a move that black should always make (if he can) when playing a game. These 
values will never be encountered in other situations, as Jung as Hie Visit count Ls limited to 
a maximum value of 3<J 7 
//define BLACKHASLINE OxFF 
//define WHTTEHASLINE OxFD 


r Blacky is the mast recently placed one. Black I the attest.When wc take back a move, 
we remove the most recent (3), 2 becomes 3,1 becomes 2 and 1 (oldest) us up 
for grabs 7 

//define BLAQOMASK OxFOOQOQ 
//define BLACK2HASK OxOFDQOG 
//define BLACK1MASK GxOOFOOG 
//define BlACKMASK OxFFFOOO 
//define WHITE3MASK OxOOGFDQ 
//define WHITE2MASK OxOOGOFQ 
//define WHITE 1 MASK OxOOOOOF 
//define WUITKMA5K OxQQOFFF 

//define Sw&pColours(POS) (((POS)»12) * 

(((PQS)«12) AOxFFFGGO)) 

//define UntioBlacksMbvefPOS) (((PCS) & WHITEWASH) + \ 


(((P0S) «4) & (HIACK3HASK+BUCK2MASK))) 

//define WrappitigUndoWhitesMove (F0S) \ 

C C(K)S) fir BLACKMASK) I ( ( [P0S)«4) i(WHITE3MSK+WHITE2MASK)) 

\ 

I (((POS) >>8) MfflITElMASK)) 


//define AdvanceWhiteToMove(POS) \ 

(f(POS) 4 BTACKMASK) + ((CFOS) »4) fr(WHITE 1MASK + 
WHTTE2MASK))) 

//define AdvanceBlackToNove [PCS) \ 

(((POS) fc WHTTEMASK) + ((CFOS) »4) & (BLACK1MASK + 
BLACK2MASK)}) 


//define Ee t Whi t eToMov eF 1 a g (FT AG) whi t eToMo ve Da t a | - (OxB0» (FLAGl) 
jfd ef in r SetWh i t eToMo veF lag 16 (Ft AG) \ 

whit eToHoveDatal b |= (0xBD>>(FLAG)) 


//define SetWhiteToMoveHinDistance (VAL) ASSERT ((VAL) <8): \ 
whiteToHoveData 4= QxFl; \ 

whiteToMoveflata j= £(VAL)«I) 


//define SetWhiteToNaveMinDjstance16(VAL) ASS£RX((VAL)<B>; \ 
whiteToHoveData16 &= QxFF; 


\ 


whiteToMcveDatal6 |= ((VAL)«8) 


//define GetWhiteToNoveMinDistance \ 

[(whiteToHoveData & OxflE)>>l) 

//define GetWhiteToMoveMinDlstanceld \ 

(whiteToMoveDatalfi » 8) 

//define SetWhiteToHoveMaxDi stance (VAL) ASSERT ((VAL) 06); ,\ 
whiteToHoveData OxQF: V 

whiteToHoveData |= ((VAL)<<4) 

//define GetWhiteToMoveMaxDi stance \ 

£(whitaToMoveData fir QxF0)»4) 


//define Se t Whi t eTuMo ve Vi sit Count (VAL) ASSERT ((VAL) <16); V 
whiteToHoveData &= GxOF: 


((VAL) «4) 


if ((VAL)>=16):WhiteToHoveData j* 
else 


«W)«4)i \ 

whit eToMoveDa ta 


//define GetWhi LeToMoveVisi tCount \ 

((whiteToHoveData fir OxFO)»4) 


static inline unsigned long Minimize/unsigned long gameFos); 
static unsigned long InitWhiteLosses(unsigned char 
*whiteToMove, 

unsigned long *listl)* 

static inline unsigned long HakeFreeSpaceMask( 
unsigned long gamePos); 

static inline unsigned long MakeFreeSpaceMasko( 
unsigned long gameFos): 

static inline unsigned long MakeFreaSpaceMaskA£ 
unsigned long gamePos): 

static inline unsigned long MskeFreeSpaceMaskl( 
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unsigned long gamePos); 

static inline unsigned long HakeFreeSpsceMask2( 
unsigned long gamePos); 

static inline unsigned long MukeFreeSpaceMask)( 
unsigned long. gameFos): 

static inline unsigned long GetMoveFromMask(unsigned long 
&inask]: 

static inline unsigned long EncodePos(unsigned long pos); 
static inline unsigned long Encode5Pos(unsigned long pos); 

//x3: 0 ,1 or 2(=5) (2 bits) 1344 } could he combined into 4 hits if necessary 

//x2: mas 8 Gbits) 10-12 ) 

//xl:nwx7 Gbits) 7-9 

//y3) max 6*5-30 (5 bits) 2^ 

m\ 

//vl:max4 (2 bits) 0-1 

//highest value is Obit)] 1111 Mil 1111 

|define GettfTM(pos) whi teToHbve [EncodePos(pos) J 

(/define ItetWTMipos, val) whiteToMpve [EncodePos (pos) ] = (val) 

(/define GetWTM5 (pos) vhiteToMove5 |Encode6Fos{(pos) «4) »Z 3 
#define SetWTM5(pos,val} \ 

whiteToMove5[Encade5Fos((pos)<<4)>>2] - (val) 


MstkeFnsttion 

sialic unsigned long MakePositionOorsg x[6] Jong y[6]) 
f 

long ii; 

unsigned long position = 0: 
for (ii =0; ii < 6; lift) 

l 

position^ (x [11] <<?,)<< (4* ii)) ; 

J 

for (ii =0; ii < 6: ii++) 

l 

poeition-M (yliij )«(4*ii)): 

I 

return(position); 


EncxxtcPoss 

static inline unsigned long EncodePos(unsigned long pos) 

I 

unsigned long temp.tenp2.y3Val,y2Val; 
unsigned long blackl,black2.blackl.white!*vhite2.whitel; 
unsigned long result “ (posAOxFGOOOO) » (20 - 13); 
if (pos & 0x400000) //x3 position Is 5 

result ■= (3 « 13): //coovcrt 0x5. . to Ux2... 

ASSERT(result <= Ux4UU0); 

ASSERT((result & 0x6000) = result): 

black 3 = CposMLACK3MASK)»BLACK3POS; 
black! - (postELACK2MASK) ,)>ELACK2POS; 

//ena>de x2 ■ if \2 > x3 then decrease value by I 

temp “ black! black!; 

iemp2 - (pus & BLACK2MA5K) ({te®p b 0x80000000)»1 r j): 
temp2 “ (pos & OxCOOOO)>>2: //aspos 3 and 7 are invalid 

ASSERT((temp2 » (16 10)) <= CxlCOO); 

ASSERT ({(tejnp2 » (16 - 10)) 4 OxlCOO) — 

(temp2 » (16 - 10))); 
result |= (temp2 » (16 - 10)); 

//encode xl if x I >x3 decrease value by I, same for > >1 
black! - (pos 6 BLACK 1 MASK)»BLACK1POS; 
temp = black! j black!: 

tetnpZ = (pos b BLACK1MASK) - ((temp & 0x80000000} »19); 

temp = black! - blackl; 

tentp2 -= ((temp 4 Gx80000000)»l9); 

temp2 (pos 4 GxCOOO)»2j //as pos 3 and 7 are invalid 

ASSERTS(temp2 » (12 7)) <= 0x380); 

ASSERTf £(temp2 » (12 /)) 6 0x380) “ (temp2 » (12 

/))): 

result |* (tetnp2 » (12 - 7)): 

//encode v3 - if y3 > x3 decrease value by 1, same for > x2 and > xl. 
vbite3 = (pos b WHTTE3MASK)»WHITE3POS; 
temp " black! white3: 

y3Val - (pos 4 W1HTE3HASK) ((temp 6 0x80000000)»23) ; 
temp = black! - white!: 


y3Val -= ((temp 4 0x80000000) »23); 

temp = blackl * white3; 

y3Val — ((temp 4 OxSOOOOOOO)»23); 

ylVril -= (pos 4 GxC00}»2: //as pos 3and7 are invalid 

//encode y2 - if y3 > x3 tkrerease value by l h same for > \2,>\l and > y3. 
white2 = [pos & WH1TE2MASK) »WH1TE2F0S; 
temp = black! - white!; 

y2?ai - (pos & WHITE 2MASK) - ((temp 6 0x80000000)»27); 

temp = black! - whitel; 

y2Val -= ((temp 4 0x30000000)»27); 

temp = blackl - white!; 

ySVal = ((temp 6 0x80000000)» 11)z 

temp = white! white 2; 

y2Val -= ((temp 4 0x80000000)>>27}; 

y2Val = (pos 4 0xCG)»2: //& pos 3 and 7 arc invalid 

y2Vai = y2Val « 4; //to befog into fore with y3 

temp = £y3Val * 5 + y2Val) » (fi - 2); 

ASSERT(temp <- 0x70); 

ASSERT(£temp 6 0x70) = Lump); 
result |= temp; 

//encode yl - if y3 > \5 decrease value by I P same for > x2 T >xl ami > y5. 
whitel = (pos 6 WHITE 1MASK) >> WHITE IPOS: 
temp = black! - whitel; 

temp2 - (pos & WHTTE1MASK) - ((temp 6 0x80000000)»31); 

temp - black2 white!; 

temp2 = ((lemp 8 0x80000000)»31); 

temp - blackl whitel; 

temp2 — ((temp 4 0x80000000) »31); 

temp “ vhite3 - whitel; 

temp! ((temp 4 0x80000000)>>31); 

temp = white2 - whitel; 

Lcmp2 - { (temp 4 0x80000000) »31); 

tenp2 ^ (pos 4 0xC)»2: //aspos3and7areinvaiid 

ASSERT(temp! <= 0x3); 
result temp2; 

ASSERT{result < 0x4700); 

//highest position involves b3 in centre ;uid b2 on an edge, so 
/AalucIsOblOUOl 101 xxxxxxx or0x46FF 

return(result): 

l 

r 

* ike online code listing lor Encoders 
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Minimize 

MinimixcO 

lire aim of tins function is to find a new value for gamePos ibis is lot ally equivalent 
(a reflection or nrtatkm of the airrent one), Lxtt which hits a Muailer value. 

We first calculate whether we can minimize it by reflecting the board across its horizontal 
and/or vertical lines of symmetry (x= I ;uid > r = I ).Wr then m reflecting it on a diagonal 
(x=y),With rhe H possible combinations of these reflections, we can swatch (toms every 
symmetry of tire boaid to every otlrer. 

lire function uses a rather confusing algorithm in order to minimize coiulitiontil bnmdies 
to improve on pipditung. 

static unsigned long Kiplmize(unsigned long gamcPos) 

( 

unsigned long xBitfiold, ybitfluid; 
unsigned long xCountFramLeft t yGountFrozaTop; 
unsigned long swapped; 

/* By XOtt-ing every' x bit-pair with IHjO l. we I me a t in ail even bit-position 

(counting from MSB, first is zero) ifx should be counted from the right, and 

a I in an wkl hit-positfon ami a 0 in an even bitfositkm if x slreuld Ire ctxmted 

from the right. If neither are I, ir docs mx matter for ibis x coordinate which 

side we start counting from. 7 

xBitfieid * gamePos 6 X_MASK; 

xBitfield rt = 0x444444; //one in every x field 

/* Now we count tire leading zeros on lire resniLam bit-fiekL 

If there is ;tn M number of leading zeros, we should count from the left. 

]f there is art even number, we should count from tire right. 7 
xCounlFromLeft = entlzwfxRftfield) h 0x01: 
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P Do a similar thing for v V 

yBirfield - gameFos A YJ1ASK; 

yBitfield "= OxLlIllL; //one in every j fkfcl 

yCountFromTop = _cntizv(yBitfield) & 0x0h 

P U Ih t x ikkfc m* to he counted from rh*' right, or the y fields from rite 
bottom, w* (Kxd tti suhtrjn the initial whir fnmi 2/lwo's compiemtnt arithmetic 
for cadi 2-Ni field that is to be swapped grits 2+< T vJuc)+ l or (lb l l-Kflbl I A value). 
Tills :ihv;r)\ gives a carryover hit, so to caned out die overflow we subtract 
flbl HO sir tibl I’KOh IL \m 7 

if (xCuuntFroinLelt — 0 AA yCountFromTop *• 0) 

I 

P need to subtract every held from 2 7 

gamePos - XY MASK + (XY_MASK A gameFos) - 0x1555554; 

I 

else if (xCountFromLeft = 0) 

I 

gaaeFos = XJ4ASK + [X_MA$K A gamePos) - 0x1111110; 

else if (yCountFromTop *= 05 
I 

gameFos = Y MASK + (Y_MASK A gamePos) - 0x444444: 


P li may he tJxit we on make flic gamePos value smaller hy swapping the x ami y 
cooftlnatcs This is equivalent to reflecting the board in the line y=x.Thc 
quickest way of knowing if we sfioukl do this is jsm to tn if and see 7 

swapped * ((gamePos « 2) A OxCCCCCC) + 

((gamePos » 2) A 0x333333): 
if [swapped <“ gsmePos) 

garaePos " swapped; 

return (gameFos) ; 


UiilWIuieljOjffiCS 

static unsigned long TnltWhileLosses(unsigned char VMteTpMove h 
unsigned long MistH 
( 

/" Hrsit is most significant 7 

lung virmingLineXE9] [3J-I I0,1*2J. 10,2*1). [1 * 0 * 2 ]* 

10,0.01, {0,0,01* (0,0,01 + 

10.1.21, {0.2,1k n.0 P 2[ 1: 

long winningLineY [9)[3]^I 10.3,2], [0.2,11. [1.0.21, 

10.1.21. [0.2,11, (1,0,21, 

(I,Ml. [1,1,11, 11,1,1) ); 

long full[3][3); 
long skip; 

lung i.il.jj.xincr.yfncrr 

lung list1Pus - 0: 

unsigned long posl,pos2,pos3; 

lung vhiteHasUne; 

unsigned long pos,mini mi zedPos: 

for (1-0: K0x4/00: f*=32> //mi and 0x02 an: valid 
dch k( whiteToMove.i); 


Donelidt: 

for {i-0;i<9;HH) 

I 

lung xffiH&.0,0,0,0,Oh 

long yfftHfl.0.0,0,0.01: 

x(0|**0:x[ t J^O :x f2]^=0;x [3]=0 14]—0:x[5l=0; 

yfOl’^O :y [ ll“0 :y [2]“0;y [3J^0 ;y [4i=0:yf5]=0; 

x [b] =winningLineX [i] [0]; 
xt4j^winningLineXfil[I]; 
x[3j-winningUneX[ i] [2] ; 
y[5] =winningLirieY [l] [0]; 
y[4]^winningLincY[i][1]; 

yf3l“winnIngLIije¥[i] [2]; 

while(l) 

I 

while(l) 

I 

for(ii“0;ii<3;{i ++) 



// 


// 


// 


full[x[iill[yriill+T; 

\ 

skip = false; 

for[ii=0;ii<3;ii++) 



skip ~ true; 


if(Iskip) 

( 

pos=MakePosition{x,y); 
minimized Pos°Minlmlze(pos); 

if (minimizedPos == pos) 

{ 

posl - [(pos A WHITE 1 MASK)»WIUTE1F0S); 
pos2 - ((pus A WHITE2MASK}»WHtTE2POS); 
pns3 - ((pos A WII1TE3MASK5»WHITE3F0S): 
whiteHasLine " false: 
if ((posl A 0x3) “ (pos2 A 0x03) M 
[posl A 0x3) = [pos3 A 0x03)) 
whiteHasLine “ true; 
if ((posl A QxC) “ (pus2 A OxOC) AA 
(posl A OxC) “ [pos 3 A 0x00) 
whiteHasT. I ne = true; 

If ({posl A 0x3) = t (posl A OxOC)»2) AA 
(pus2 A 0x3) = ((pos2 A OxOC)»2) AA 
[pos3 A 0x3) “ ((pos3 A OxOC)»2)) 
whiteHAsLine “ true: 

if [whiteHasLine) 

* 

A,SSFJlT(toWTM[pus)“0 || CetWTM(pos)—WHITEHASLINE) ; 
SetkTTM (po s, W111TEHAS LI ME); 
whttcToMove[posf =WlimaiASLINH; 

] 

else 

I 

ASSERT(GetWTM (pos 5 —0 || GetWTM Epos)—BLACmSLINE): 

posl - Mlniml?te{SwapColours(poa)): 

ASSERT { GetWTM (pus 1 )=0 | | CetWTM(pusl )^=WHITEHASLINE): 
SetWTMfpusl.WHITEHASLINE); 

whtteToMovrJposll =WHflHlASliNE; 

listl [lietlPos++l “ pos; 

SetWTM[pos,BLACKHASLTNE); 

whrtcToMuvefpusl - RjArKHASlINF;, 

1 

I 

I 


xlner = 0; 

vhi!e(+*[x[xlncrj) 3) 

I 

xtxlncr1=0; 
xlncr++: 
if(xlnc.r m 3) 
break: 

) 

if (xincr = 3) break; 

) 

ylncr - 0; 

while(++{y[ylncrl) = 3) 
f 

yrylncr}=0: 

yTncH-+; 

If(ylncr = 3) 
break: 

I 

if {ylncr — 3) break; 

1 

) 

return (list1Pus); 

) 


P 

* See online oxk listing for LnilWliiteLowo*5 
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MakcFreeSpaceMask 

static inline unsigned long HakeFreeSpaeeMask{unsigned long 

gamePos) 

I 

unsigned long mask ” DxEEEOOQOO; 

mask A = ((unsigned long)l«31}» 

((gaiireFos&BUCOHASK) »ELACK3P0S); 
mask ((unsigned long)l«31)» 

{(gamePosOLACK2MSK)»BLACK2POSj; 
mask A - ((unsigned long)l«31)» 

((garaeBosSBlACK I MASK) )>BLACKlPOS); 
mask ((unsigned longJKOl)» 

((gameFos&WHITEBHASK) »UHITE3P0S); 
mask * *= ((unsigned long)I«31)» 

((garaePos&WHITE2MASK) »WHiTE2P0S): 
mask ((unsigned long)l«31)» 

((gawePos&WHITElMASK) »WHITE 1 FG$): 

return(mask); 

I 

r 

* See online code listing for MakcFredjpaceMx&X X—1.5 

7 


GecMovd^omMask 

static inline unsigned long GetWoveFromMask (unsigned long task) 

[ 

unsigned long freePos ** cntlawtaask); 

(n$sk) *= {(unsigned long) (l«31)»freePos); 
return(frefcPos): 


GeaeraicWl lite U tMovdJsita 

statin unsigned long CenerateWhiteToHovcData(unsi gned char 

*whiteToMove, unsigned long •fulliist, unsigned long 
fullListLen} 

( 

unsigned long dtstaneeFromWin = 0; 
unsigned long fullListPos = Q; 
unsigned long depthMax = Ful iListLan; 

//depthMax Ls ihc lirst list member belonging to the current depth 

while(fullListFos < depthMax) 

l 

unsigned long ii; 

unsigned long garaePos - fullList[fullListPosi+j; 
unsigned long mask] _ HakeFreeSpaceHask(gamePos): 

//mask I ts a mask of the free glares Thai black could Itavc just moved from 

//removf tjladi's most recent move 
gamePos = (gamePos & WHITEMASK) | 

((gamePos « 4} & (ELACK3MASK | aUCK2KASK)h 

//do lor the 3 places die most recent block mo\t could have euroe faun 

for <ii=0;li<3:ii++) 

1 

unsigned long whiteToMovuDats* mask2, oldWhitePos* jj, 
partEncodedLastRoundPos ; 

//gut a position from die mask 

unsigned long blackPiecel = GetMoveFrontfa.sk(maakl); 

//get position as it was hekne black moved 
unsigned long prevGamePos = gamePoa | 

(blackPieceJ « BUCK 1 POE); 

//gel tile dila for Mack on the postion with bkek about to move 

//to do this, swap the colours, minimize, and read from the whiteToMove data 

unsigned long tempGamePos {(pEevGamePos»12) + 

£ (prevGainePos«l 2) &0xFFF00G)); 

tempGiinePoG = HinimizeftempGamePos); 
vhit eToMoveDat a “ Get WTM (t cmpGamePos); //whiteToMovtltompGamePus [; 

If ((whiteToHoveData & BLACKMUSTWIN) bft 

(GetWhiteToMoveMinDistance < disianceFromWin)) 

I 

1 1 z H>k if the position b one white can force a win from before black has 
a chance of forcing a win. If t is. give up on dial position 7 

continue; 


T convert a position of the form 321CBA to 321 BAGThis lets us minimize 
the position as it will lx: when wc lake back white s last move, and still know 
where that move we are Liking back was from - even though the position 
code may have been changed by minimization 7 

prevGamePos = (prevGsmePou k RLACKMASK) | 

((prevGaraePos«4) & (WHITE3KASK+WH1TE2MA5K)) 

| ((prnvGEjmePos»B) £ WHITE1MASK) ; 
prevGamsPos = Minimize(prevGamePos)? 
mask2 = HakeFreeSpaceMask(pruvGamePos): 
oldWhiteFos = (prevGamePos £ OxF): 
provGamePos &= (-WHITE1MASK); 

/^encode as much of prevGameFos as we can at diis staged will encode the 
last 2 bits (white I.), and only that, in the inner loop 7 

partEncodedLaetkoundPos w (EncodeFos{prevGatiiePos) ft OxFFFC}; 

//undo whites last move to cadi of die 3 places it could have come from 

for (jj=0:jj<3:jj++) 

I 

unsigned long mankG ponnibleMove, eneLastRoundPos; 
unsigned long WhitePiece * GetMoveFroti5Hask(mask2) : 
unsigned long lastRoundPos - prevGamePos | 

(whitePiece C< WHTTEIPOS); 

//whitcToMoveData - 

// GetWTMf last Rt iundR&)7/wliite'lbMQve | lastRoufidPos]; 

( 

unsigned long temp - {(lastRoundPos & OxFODUOO)»20) 

vkltepiece: 

unsigned long terap2 " whitePieee 

((temp h 0x80000000) »3I); 

temp = (UastRoundPos & OxFOOOO)>>16) - whitePiece: 

temp2 -- ({temp & OxSOOOCKJOO)»31); 

temp = ( Hae»tRoundPos ^ 0xF000)>M2) whitePiece; 

temp 2 — ((Letup h 0x80000000) »31): 

temp — ((lastRouridPos 6 OxFOO)»fl) whitePiece; 

temp2 *“ ((temp & 0x80000000)»31): 

temp ” {(lastRoundPos & OxFO)»4) whitePiece; 

iemp2 — ((temp & 0x80000000)»il); 

temp2 - (lastRoundPos & 0xC)»2: //^ pos 3 anti 7 arc invalid 

ASSERT(temp2 0x3): 

encLastRoundPos ” partEncodedUntRoundPos | temp2: 

I 

//end asiRouiidPuh = Bx^xkRjs(!astRi>urKll3>5); 

^iteloMoveDats = whiteToMove [enc Last Round Pas 3: 

If (whiteToMoveflsta — BLACKHASLINE || 
will t eToHo veDn t a = WHITEHASLINE) 
continue; 

rdon’i hotlKT to track hack to jxisititmN what a 

player has a line (someone has alrcatlv^ w^in) 7 

if (whiteTuMoveData & WTMiLAGMASK — 0) 
t 

//reectrcl the minimum number of rounds mini btick maikcsa line 

SetWhiteToMuveHtnDiatance (distancefrumWin); 

I 

if (whiteToMoveData 8 Br*ACKmiSTWIN) 

i 

//dun l do anyUting more for tins position if wc already know it is a winner 

continue; 

] 

t flet the new frue^pacc mask ;uul work mt which nix' Ls the onv wc juse 
took back whites move from (oldWliitePlH) 7 

mask3 = M;ikeFreeSpaceMaak(lafltRoundPos); 
possibleHove = GetMoveFtutnMafik (mankl); 
if (pofisibieMove — oldWlii toPos) 

SetWhiteTt>HoveF!ag(Q); 
ponsibleMove - GetMoveFroatflflsk(mt[uk3); 
if (possibleMove =* oldWhitePos) 

SetWhiteToMoveFlagCl); 
possibleMove ™ GetMoveFrotuMasktEtask^); 
if (possibleMovu ~* oldWhitePos) 

SetWhiteTuMoveFlag(2); 

if (vhit eToMoveData > WTMFLAGMASK) 

[ 

ful lUst f full ListLen++] ^lastRouudPos: 
whiLeToMovpData H-; 
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SetWhiteToHoveMaxiM stance (distanceFroraVinl* 

I 

// whilcToMowfbstKoiflKlPosj = whitcTbMuvcData; 

//SctWTM(bsiRoimdPos t wJ liic IbMoveDaia); 

ASSERT( (vhiteToKoveData & OxFHJO) — 0)- 
whiteToHove EencLastRoundPos] = whiteToHoveData: 


1 

1 

if (fullListPos < depthHax) 
continue; 

depthMax = fullListLen; 

r Increase dte&nccFiti triWin-We must limit it to 7 to fit in a spat e of 
3 bite for mirKlistincc. It would not lx the axJ of the wotid if dim; 
wiis ;t cap on this value;and its it happens tixae atv no definite winning 
setups with a minimum distance of >7,7 
if (distauceFraraWin < 7) 
diet anc eFromWln++; 


retu m(fuiiLis tLen); 

1 

r 

9 See online rode listing for fAiKrateVt1uleibM(WcXDaia T X=l . 5 

7 


BestMovebPietes 

//static unsigned k>ng CkdksiMcwefunsigiicd Vmg gamete, 

// LtUMgrtcd diar VhiteToMi ivr) 

static unsigned long BesUJovebPieces C 

unsigned long gumePos, unsigned char ‘whitaToMove) 

I 

unsigned long blatkHece3 *vhitePlece3; 

unsigned long nextGamePos,gp2,tolourSwappcdPosition; 

unsigned long whiteToMbveDat .a , tn InD i sLance: 

unsigned long ctaekl , tnaok7; 

long score*beatScore; 

long bestHove; 

long ii.jj; 

bestScore = 100DO; 

maukl - MakeF reeS pa c eiia s k {garaePos); 
gamePos = AdvanceBlackToMovefgamoPos); 
for £ii * 0; il < 3; ii++) 

( 

score “ D: 

blackPince3 * GetMoveFroitiMask(iiia£kl); 
nextGamePos = (gamePos & (-BLACK3MASK)) | 

(blackFiece3 « RLAOOPOSh 

vhiteTaHoveOata = GetWTW(Hinimi xefnextGanePosJ J; 
if (vrtiiteToHoveOa ta — HTACKHASLiKE) 

//can win instantly by making a line 

I 

//printfi ,u| yd wins outrigbrbp \bkciFitce3); 
return (blackPiecel); 

I 

tnlnDi stance “ GetWhiteToMovd^inD5 stance; 

if CwhiteToMoveD&ta ^ 0x1) 

//can win in the furore starting with this move 

I 

I* Highest score goes to smallest distance we arc sure to win in (maxdtetancc) 

7 

//phntfT^Jd wins in ’tekl^id 

//n.n irufe\n H , btockPfcceB t Gct Whitt/R )M<>vcMinfJi sluxv, 

// Gel Vil iilcT( >M< >«MaxDfctt&ce); 

score = 10000-GetWhiteToMoveHaxDlstance; 

I 

else //took at possibilities for wliilr’s next mow 

1 

mank2 ■ MakeFree$paceMask(nextGamePos); 
nextGanePos “ AdvanceWhiteToMove(nextGaraePos); 

For (jj - 0; jj < 3; jj++) 

! 

vhitePiece3 • GetHoveFromMa£k(niask2); 
gp2 & (nextCanePos 6 fHf/RTTE3KASiO) | 

(wblrePleceB « UUITE3POS); 

P gp2 is now one of 3 possible biadf-to-movt positions arising from 


die current immediate hkxk moves. 7 

colourSvappedPosition - SwapColours(gp 2): 
whit eToHoveDa t a 3 Ge tWTH(FLLnimi ze (C olourSwa pped Pos11ion)); 
if (wMteTottoveData & 1) 

I 

/*The worst stuatiun is that one of the postals is a biack loses 
position with a small mirKlistance (it. one that die opponent is 
ver>' likely to see), 7 

if (vhiteToMoveData = BLACKHASLINE) 
score » 101: 

else If (score 1*= -101) 

score = ‘100 + GetWhiteToMoveMi nDl stance; 

I 

\ 

if (score — 0) 

I 

r add support for not visiting die suix location over & over""/ 
r if we have not yet scored for anydiing, tlx best bet is a black move for 
which some of die subsequent moves white roukl make arc fetal, witii a 
large min-distnixc 

'[Ids represents moves that white could easily not nodee arc fetal, ami play 
by mistake 7 

score “ mlnDiatancp; 

) 

I 

If (score > bestScore) 

I 

bestMove = blackFiece3; 
bestScore — score; 

1 

1 

rerum (bestMove); 

1 

r 

9 Sec online code listing for lJcstMovcXPieves r X=0.,5 

7 

unsigned long gCurrentGamePos111 on, gCurtentRound: 
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PlayTrilitc 

Boa rd Position PiayTrilite( 

const Board triliteBoard, f ament State of the Board 7 
Boa rdPosition a pponentPre viousFlay, 

r the BoiirdPoMtiun your opponent Iasi played 7 
lot pi aye rNurabe r. /* I if yi hi arc player1,2 if you are player 2 7 

Boolean newGame P true the tirst lime you arc ealktUbr a new game 

7 

) 

{ 

unsigned long *listl P *list2. "list!. *list4 H 'listl, 

‘fuHList; 

unsigned long 1 i s11 Le n . list2Ien *fullListLen ; 
unsigned long list3Len.list4Len.list5Len; 
unsigned long ii; 

unsigned char 1 whit eToMove, T whiteToMove5: 
unsigned short *whiteToMove4. ‘whiteToMove3, *whiteToMove2. 
*vhiteToHovel; 

BoardPosllion regultBoardPosition; 

unsigned long bestMove, myOppooentPreviousPlay: 

if [gMeraory = OL) //see if data nmly lo be generated 

{ 

whiteToMove4 = (unsigned short")NewPtr(0x5 1B0 "2); 

vhiteToMove3 - (unsigned short")NewPtr( 1310*?.): 

whit eToMove 2 = (unsigned s ho rt *)NewFt r(90'2): 

whiteToMove1 = (un signed s hort *)HewPt r(8 * 2 ); 

gWhiteToHove4 = whiteToMove^: 

gWhiteToMove! - whiteToMove!; 

gWhiteToMove/ = whiteToMove/; 

gWhiteToMovel = whiteToMove1; 

gMefltory - NewPtr (70000) ; 

if (gMewory = OL) //out of memory (shaiddttT happen!) 

( 

DebugS t r["\pOut of memo ryI"h 
re suit Boa rd Posiliorc=kNoF os i tioni 
return(resuitBoardFosition): 

] 

//init temporary storage (lists of winning pavilions) 

list3 " (unsigned long*)NewPtr(4MOO): 
list2 = (unsigned long*)KewFtr(4*100): 
list 4 = (unsigned 1ong *)He wPt r(4 * 100): 
list5 = (un sigu ed 1ong*)NewPtr(4 *100); 
whiteToMove - (unsigned char")£{(tong)gMemnry £ OxFFFFFFEO) + 

32); //fiiock size 0x4700 

whiteToMove5 = (unsigned char*)((char")whiteToMove + 0x4700); 

//block star Oxl IQ) 

fullList ■= (unsigned long*)((char*)whiteToMoveb + OxllCO): 
//block si/c 0x2000 

listl = (unsigned long*) ((char*)fullList + 0x2000): 

//block size 0x0800 
t full Iuls 2026/-7200 winners 
5-piece oaks read from full to listl (419/1800 winners) 

3-piece oaks read from listl to list / (16/60 winners) 

I -piece calcs read from Eist2 lo lisi'i 
4 piece calcs read from hill to list/ (58/360 winners) 

/ piece calcs read from list/ to listd 7 
//dear arrays 

for (ii=O;ii<£0x51bO/2);£i++) 

((unsigned long*)whiteToMuve4)[ 1 i ] - 0; 
for (ii' a 0:ii<(l310/2) ;ii++) 

((unsigned long*)whiteToMove!)[ii] = 0; 
for (ii=0;li<(90/2);il++) 

((unsigned long*)whiteToMove/)l iij = 0: 
for (ii"0:ii<£8/2);li++) 

((unsigned long*)whlteToMnvel)fill =0; 

fullListLen - InltWhit(.’Losses(whitcToMove. fullList): 
fullListLen “ GenerateWhiteToMoveData(whiteToMove, fullList. 

fullListLen): 

listlLen ” InitWhiteLosses5(whit eToMovei. listl): 
listlLen “ GenerateWhiteToMove5Data{whiteToMove, whiteToMovcS* 
fullList. fullListLen, 

11st 1♦ listlLen): 

1ist 3 Len - Gene rat eWhilcToMovcADa ta(whiteToMove, whit eToMo ve 4, 
fullList * fullListLen, list3); 

Hst2Len - GenerateWhiteToMove3Oat a(whiteToMnve5. 
whiteToMove!-. 
listl. listlLen. list/): 


1is14Len = Gene r ateWhit eToMove2 Data(whiL eToMove4, 
whiteToMove/* 
lists. list3Len. Iist4); 

listiLen - GenerateWhiteToMovelDa-a(whiteToMove3, 
whiteToMoveI, 
list2. 1lst2Len, liatS); 

i 

else 

t 

//init local variables from global; 

whitnToMove4 = gWhiteToMove4: 
whiteToMoveS = gWhiteToMove3: 
whiteToMove/ - gWhiteToMove/: 
whiteToMove1 ^ gWldteToMovel: 

whiteToMove = (unsigned char*)(((long)gMemory b OxFFFFFEEO) + 
32): //block star (tot4700 

whiteToMove5 = (unsigned char*)((char*)whiteToMove + 0x4700): 
//block size 0x1 IQ) 

fulLList - (unsigned long*)({char*)whiteToMoveb + 0x1 ICO); 
f/Uock size 0x2000 

listl “ (unsigned long")((char*]fullList i 0x2000); 

//block star 0x0800 


//oppoi^ntPreviousPlay must be convened in ihc imcmal rcpix^entation h where 0,4 
// iiixl 8 arc the values of the pieces in die Idi-limd column of ihc board 

ii(opponen tP revious Play >" kBo11omLeft) 
myOpponentFrevinusFlay “ (unsigned long)opponentFreviousPlay + 

2: 

else if (opponentPreviousFlay >= kCenterLeft) 
myOpponentPreviousPlay * (unsigned long)opponent?reviousPlay + 

1 ; 

else 

myOpponentPreviousPlay - (unsigned long)opponentPreviousPlay; 

if (newGame) 

I 

tf (playerMuffiber — 1) 

I 

gCurrentRound = 1; 

I 

else if (playerNumber “ 2) 

f 

gCurrentRound = /: 

I 

i 

else 

{ 

gCurrentRound += 2\ 

1 

switch(gCur r entRound) 

t 

case 1: 

gCurrentGame Position = 0: 

bestMove a BestKoveOPieees(whiteToMove/. whiteToMoveI): 

gCutrenlGamcPosition * bestMove: 

break; 

case 2: 

gCurrentGartePosition = myCpponenL PreviousPlay; 
bestMove ^ BestMovelPiece(gCurrentCauePosiLion. 

whiteToMove!* whiteToMove/): 
gCurrentGainePositioti - (gCurrentGamePosition « 4) j 

bestMove; //I to IA 

break: 
case 3: 

gCurrentGataePosition - (gCurrentGamePoslllon « 4) | 

myOp pot icm Previn us Play: 

bestMove ~ BestMove2Fieces(gCurrentGameFosiLiori H 

whit eToMove4, wh iL eToMove3}; 
gCurrentCaiaePosltion ~ gCurrentGameFosition | 

(bestMove << 8): //lAto21A 

break; 
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rase 4: 

gCurmuGaracPosit itai = gCwrentGomePosition | 

(myOpponentFreviousPlay « 8) j 
bestMove = BeetMovelPieces(gCurrentGaiiiePosition, 

whiteToMoveb, vhiteToMbve4): 
gCurrentGamePositian - ((gCmrresitGomePoaltioti « 4} & 

OxFFOO) | 

(gCSurrentGamePositlon 6 OxF) | 

(heorMove « 4): ffl IA to 21 HA 

break: 
case b: 

gCurrentGamePosition - 

({gCurrentGaraePoflitiori <<41 & OxFFOO) | 
{gCurrentGamePosition k OxF) | 
(myOpponentPrevtoufjPlay « 4) ; 
bestMove “■ ftefitMn vei Pierrot gCu rrentGamePosIt lon, 

wh 11 eToMo ve. whi l e'l'oHove b } : 
gCurremGamePosition “ gCurrentCamePosition | 

(bestMove « 16): //21BA to 321UA 

break: 
case 6: 

gCur rent Game Position = gCurrentGamePoEitim | 

(myOpponentPrevioiiRPlay << 16): 
bentHovo * RestHove5Pfeces (gCu rrent GartePosilion, 
wiiiteToMove); 

gCurrentCamePosition “ ({gCurrentGameFosition « 4) & 
UxFFFQOO) | 

(gCurrentGamePosition & QzTF) j 
(bestHove « ft) //$21M to 521CBA 

break; 


raso 7: 

gCur rent Game Posit im ” 

((gCurrentCamePositiort « 4) & OxFFFUOQ) [ 
(gCurrentCaaePoeition & OxFF) | 

(myOpponentPreviousPiay « B): 
beatMove - BeatHovebPiecesCgCurrentGamePosition, 

whiteToMove); 

gCiirrentGamePoEitioti * 

Adv >\ n cc H1 atkT&Move(gCur rati LGomePosiL ion) ; 
gCurroniGaroePosi L ion |= (best Move « BLACK! PCS): 
break; 

default: // gUimiuKcHmd > 6 

if CplayerHuraber — 1) 

I 

gCu r rentGamePosit ion = 

AdvnnroWh i teToMovefgGurronlGfimePosi i Son); 
gCurrentGome Pos U i on (rayOpponenL Previous Play « 

WH1TH3P0SS; 

bestMove “ BestMovebPiecestgCurrentGamePosition. 

whiteToMove): 

gCutreniGamePosition — 

AdvanceslackToMove(gCurrentGamePoaition); 
gCurrentGamePosition |“ (beatMove << BLACK!POS): 

elan 

E 

gCurrentGamePosition = 

Ad vane eBl a ckToMove(gCur rentGamePosition1; 
gCurrentGamePosition |- (royOpponentPreviousPlay « 

BLACK!POS); 

beetMove ■* 

BentMovebPiecen(SvapColon rs(gCu r rentGemeFosA11 on), 
whiLeToMove}; 
gCurrertiGanteFosliion - 

Adv Einc eWhi t eToMove (gCurreatCamePosition): 
gGurrentGamePosition |= (bestHove « WHITE3P0S): 

break: 


I 

//owm NestMnve io exitvrol representation 

rcsult flou r d Posilion = 

(BoardPoaitioTi) (bestHove - (bestKove / A)): 
return(resultBoardPosition); 
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essential reference resource for 
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THINK Reference Compiler, which 
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into your own compact, searchable 
THINK Reference databases. 
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Is 4D 6 .7 Really Worth it for RAD 
Developers? 

By Matthew Stoton 

Radically Different 

The main goal of any high-end database is to 
deploy information as fast and easily as possible. Until 
version 5, FileMaker has been the obvious choice for 
anyone; experienced or not. 4th Dimension is now 
ready to entice FileMaker users to make the switch with 
version 6.7, Now 4D lias FAD capabilities, WAP 
support, Mac OS Theme support, 24 new and 24 
modified commands and several new Internet features. 
More than enough reasons to upgrade, but will fi be 
enough to bring FileMaker users home? 

Ai.i. Entangling Web 

If you have ever used FileMaker's noi-so-instant 
web publishing then you will love 4D’s simple, and 
instant, web publishing features. It produces HTML 4 
and supports many other weh-based technologies such 
as JavaScript and XML. For those wondering about 
security, 4D .supports both SSL 2 and 3; a big bonus for 
e Commerce starters. Still, most beginners will be 
stunned by the installation process of the web assistant. 
You must open your database using the 4D In stele it, 
install the web assistant and wait. You may also have to 
edit the installed code, although the exact purpose of 
this is not mentioned. Aside from this, web publishing 
is extremely easy and actually instant. 

No Relationship? 

What about those who only need a single user 
database? This is where most would crown FileMaker 
king,,, or not, 41) has some great tools for small-time 
developers rhnt simply can t be ignored. Sure. I'll be the 
first to admit that ID. if pul in the hands of an 
unexperienced user, can be overkill. For the 
unexperienced, Filemaker's word like simplicity is great, 
yet it lacks some of the features of a lull-featured 
database like 4th Dimension, 41) has power that can't be 
found in FileMaker, although this can be troublesome at 
limes. Even if you don't need a relational database, 4D 
is still the product for you. Even if you only need to do 
simple database tasks, 41 > will boost your productivity 
like you've never seen before. 

Bugs and So Much More 

Of course you‘d hardly expect a feature packed 
program like this to be hug free. And after years of using 


a rather mediocre product, you could over look more 
interface glitches than you care to admit. Not so. With 40 
you have no reason to anyway. In FileMaker 3 the 
interface looks exactly like Apple Works 3. except for an 
ugly Microsoft Word button-bar, 4D has a similar button 
bar that looks more like AppleWorks* hut with tool-tips 
instead of an info box, II opens to a simple “open/new” 
dialog box, allowing you to open a previous database or 
make a new one. After choosing "New Database 1 ', you 
must make the structure for it. Tilts is sure to confuse 
users who used the "Define Fields" window in FileMaker. 
In the structure window you define the table, fields and 
any relationships between them. This speeds up the field¬ 
making process tremendously. After this you are required 
to create a form ; 4Ds version of FileMaker’s "layout". 
Naturally, the process of making a form is quick and easy, 
it can be completed in as little as five minutes depending 
on the size of database. A much more daunting task is 
editing a created form, tt brings up two palettes: the tools 
palette and the property list. Both palettes take up tons of 
screen space and the tools palette has no tool tips for it's 
generic looking icons. The most annoying problem is that 
when you align two objects using the align feature, both 
objects move to a central point. Unless you go deeper 
into that menu, can you bring up a more detailed 
alignment dialog. The design area isn't all faults though. 
You can choose to display many different page guides to 
assist in keeping everything in the page. Ii also offers a 
grid, rulers, grouping, mass duplication and many other 
time-saving options. 

Scientific ally Fast 

The main reason to choose 4D is its speed, or ability 
to save time. It s interlace isn't nearly as nice as that of 
Bryce, bin ii isn't all that bad either. It doesn't really 
enable you to have a "liquid work flow”, but it offers 
some really smooth easy-to-find features. Time is the 4th 
Dimension, so its no coincidence that they named the 
program 4D, I must say, ii really is fast. If for no other 
reason, buy it because it has the edge on speed. Not only 
in creating records or other automatic tasks but also in 
form creation, data importing and structure creating. All 
tasks that can slow you down on other software. 

Learn a New Language 

Although it isn't absolutely necessary, it Is advisable 
to learn the 4D programming language. By using is you 
enable greater flexibility and without this skill your 
database or application will be much less powerful, if 
you are the type that doesn't like to read manuals you 
should ai least browse through the 1600 pages. If you 
actually read the thing then you wall pick up the 
language much better. It’s language, though simple, will 
knock FileMaker users to the ground. It is not one bit like 
the all-to-familiur ScriptMaker of FileMaker. Nor is the 
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language anything like the incredibly simple Hyper Talk. 
4D,s language is much like that of FoxPro. For novices 
this is just one more Lhing to learn. For seasoned 
professionals the power of the language will allow much 
greater flexibility. Although same commands are missing 
it is a rather mature programming language that 
empowers all users, novice or pro, 

Final Word 

4lh Dimension is a great database for those who 
know databases. If you are a novice then you will not he 
able to exploit as much of IDs power as an experienced 
user would, hut you will still get incredible results. If you 
already own FileMaker then the decision to switch is an 
easy one. Even software developers will love it’s great 
functionality using RAD. Whether making u database or 
anything else time is always important, 4D gives users 
more speed and flexibility. So. whether you are a 
seasoned professional, unhappy FileMaker user or a 
complete novice, you will he at home in 4th Dimension. 

Matthew Slaton Is a software developer and writer. He uses 
RAD and visual programming tools. You can reach him at 
editorial® niactech.com or visit his site at 
www.unallymac.8m.eom, 

QuickDNS 3*0 
By Ben Baumer 

Men & Mice's QuickDNS Pro software, which is 
already the industry standard for the Macintosh, just got 
better. With version 3 0, Men & Mice have continued in 
their own footsteps by providing a stable, user-friendly 
DNS server application. This time, however, they’ve 
added a snazzy new look and a remote administration 
client, which is a godsend for anyone (like me) who Is 
ehher lazy, or using a remote DNS server. 

The first thing you 1 II notice about QuickDNS 3*0 is 
the spiffy new appearance of the icon and the server 
window. This does not, of course, bring any added 
functionality, but 1 liked it anyway. 

Other than the face-lift, the QuickDNS Pro Server 
application does not appear to have changed at all on 
the outside; it still has the same relatively small number 
of menu options and preferences. 

However, she big change with version 3.0 comes in 
the administration application, whose name has changed 
from Admin to Manager. The Manager has a new name, 
a new look, and several new features, the most 
potentially advantageous of which is the ability to 
administer QuickDNS servers remotely Along with your 
QuickDNS 30 installation comes the QuickDNS Pro 
Remote application, which is a tiny, hidden background 


application that runs alongside the server and allows the 
Manager to connect via TCP/IP. Once logged in, the 
Manager can make changes to the DNS configuration on 
as many servers as he is connected to. Since most 
primary DNS servers have at least one secondary server, 
the ability to manage all of them at the same time 
(especially when some are remote) is particularly 
powerful. One caveat is that neither QuickDNS Pro 34) 
nor the QuickDNS Remote application will run on a 6Sk 
machine, so you will need to upgrade your old systems 
to PowerPCs before upgrading your QuickDNS software. 

The QuickDNS Pro Manager has also streamlined 
some of" the features of the old QuickDNS Pro Admin. 
When you call up a domain window, you will see the 
iicader information at the top, rather than having to 
open up a second window, as was necessary under the 
older application. Also, the domain name itself tin this 
example, mactech.com) is ghosted out in each of the 
records, to help you concentrate on the important stuff. 

Another helpful new feature in the domain window 
is a sort function, which allows you to sort your records 
by name or type. If you have a large number of IP 
addresses in one of your domains, this will be a 
welcome addition in organizing your reverse records. 

All in all, QuickDNS Pro 3-0 is a must-have upgrade. 
Unless you are relying on 68k machines as your DNS 
servers, QuickDNS Pm 3-0 will make your life a lot 
easier to manage. Not only is the new appearance a 
worthwhile change, but the Remote and Manager 
applications (when used in Landcm) provide a marked 
improvement in ease-of-administration that you will 
quickly make you forget how you ever did without it. 

PageSentry 3-0 
By Ben Baumer 

There are few servers on our ncLwork that we rely 
on more than our PageSentry machine. Whether we're 
here or not, PageSentry is in constant communication 
with all of our servers, being the electronic eyes that we 
simply don’t have. How much more difficult would my 
life be if I didn't have PageSentry waking me up a 3 
A.M. to tell me that the FileMaker server is down? 
Probably much more difficult. The latest version of 
Max uni Development’s network monitoring champ 
marks a surprising improvement cm what was already a 
dynamite program. 

Like Men & Mice, Maxum must have gotten the 
message that remote administration is now a musL, 
because PageSentry 3.0 lias a built-in web server to 
provide you with just that ability. As an added bonus, the 
web server requires minimal setup. Simply bunch the 
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PageSentry application, fill our the information under the 
"web monitor" tab in the preferences menu, and connect 
to your Page Sentry machine with a web browser. 



Figure I. Setting up the PageSentry Web Monitor is 
wicked easy 


If you happen to be running another web server on 
the machine that PageSentry is on, you can change the 
port on which PageSentry runs (the default is port 80), 
Setting up the Sentries and Notifiers is much like it is in 
previous versions of PageSentry, with a few small 
changes, first, PageSentry 3-0 adds a new method of 
organizing your Sentries, called "Groups." With Groups, 
you can use a series of Sentries in combination to give 
you a better picture of what went wrong with your 
server. For example, on a web server you might have a 
standard Ping Sentry and an HTTP Sentry, If they are 
part of the same group, and one Sentry fails, the other 
will be run immediately. That way, if you get a report 
that the HTTP Sentry failed, but the Ping Sentry is still 
OK, it is likely that your web server application has 
crashed, but the machine it sell has not necessarily 
crashed. This could save you a trip to the office if you 
can fix the problem with Timbuktu. 

The second major new feature of PageSentry 3 0 works 
in conjunction with a background application called 
Proc Watch. Install P roc Watch on a remote server, and 
PageSentry will be able to check a machine for an 
individual process, To recall the previous web server 
example, this could tell you definitively whether the web 
server application had crashed. When using Proc Watch, be 
mindful of memory concerns, as ProcWatch takes up almost 
one megabyte of memory on the host computer. Clearly, 
this feature has great implications for checking up on 
servers that don’t already have a convenient type of Sentry, 
or on secure servers that don't lrave a TCP/IP connection. 


Finally, let's take a lcx>k at the PageSentry web interface. 



Figure 2, The PageSentry 3 0 Web Interface in IE 


We can see already that this window gives us much 
more information that the normal PageSentry status 
window, not to mention the fact that it can be accessed 
from anywhere in the world. Perhaps the coolest 
addition is the "Up Time Percentage" column, which 
seems fairly self-explanatory; Note that This percentage 
goes to three decimal places, and that you can reset all 
Sentries in the PageSentry application itself. Once 
you’ve had your PageSentry application running 
continuously for a couple of weeks, you will start lo get 
some really meaningful information from the "Up Time 
Percentage." After gathering statistics for almost a 
month, all but one of our servers are in the 98.5-100% 
range. These are essentially stable machines that may 
have had the occasional failure. However, one machine 
is consistently in the 97% range, and it is now no secret 
that the thing is relatively unstable. We have PageSentry 
to thank for that information. 

Current users of PageSentry will jump al the chance 
to upgrade to version 3 0. which brings several insightful 
and useful new features to a program that can already be 
the nervous system of your network. The new web-based 
administration will increase your ability to keep tabs on 
your network, both in its ability to report statistics, as 
well as create new Sentries or modify old ones from a 
remote location. But perhaps the greaLesl improvement 
conies with ProcWatch. which will increase the number 
am! type of servers that PageSentry can accurately 
monitor, thereby making ii far more powerful and useful. 
This is a worthwhile upgrade. EH 
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ONLINE 


by Jeff elites <onli ne@mactech , com> 


'['he users of Napster couldn’t possibly have known 
whai they were really doing, I hey though! they were just 
trading some music. The recording industry thought they 
were stealing. But what they were really doing, of course, 
was networking. Peer-to-peer networking, actually. In 
truth, peer-to-peer (or “p2p”) networking is nothing new, 
hut it has taken a product like Napster, with its popularity 
and legal controversy, to bring it into tile limelight. Now, 
not only are there new p2p applications, hut there are 
articles, web sites, books, and conferences springing up. 
Like other “hot" technologies (Java and XML conic to 
mind), there is a great deal of hype surrounding p2p — 
but there is also substance, if you dig deep enough. 

As a side effect of the recent interest in p2p, there has 
also been a great deal of Focus on defining what exactly 
constitutes a p2p technology. At its most basic, p2p 
networking is just client-server networking in which the 
machines involved act as clients sometimes and as servers 
other times. As a trivial example, two machines running 
FTP servers can act as peers. Some feel that “true" p2p 
application, in the modern sense, musi explicitly allow for 
the involvement of computers which are not always 
connected Lo the internet and whose IP addresses change. 
But in truth, a precise definition is beside the point, as is 
the Issue of whether a given application qualifies as p2p. 
Wbar's more important are the systems and technologies 
LhaL are being developed, and the uses to which they are 
being put. At Its core, the interesting part of p2p isn’t that 
it’s peer-based; the interesting aspect is content 
distribution, and putting this into the hands of end users. 

Content Distribution 

From its inception, the web has been about content 
distribution -— it was originally designed as a mechanism 
for sharing research papers. But end users in today’s web 
are largely passive — most users don’t produce web 
content, but only view it. But p2p technologies are 
changing this, and Luming end users into active 
participants, and they’re doing this as a matter of course 
— for instance, Napster users are automatically servers oF 
MP3 content. This is a theme which recurs in many p2p 
applications: users play the role of content providers 
without needing to make an extra effort to do so, and 
while they are becoming more involved in the Internet 
they are not necessarily participating in the web, per se — 
users are more often sharing files than creating web pages. 


This month we are going to take a look at Gnutella, 
one of the many interesting p2p applications springing up 
today, both for its technological Features and for the 
insights it gives into the pip “movement 1 . It’s a file- 
sharing-focussed p2p application, and a contender to be 
the successor to Napster. But first we are going to look at 
Napster itself, and find out why it has turned out to be 
such an important technology. 

Napster as a Paradigm 

The most Important technological insight of Napster 
was its judicious mixing of centralization and 
decentralization. In a nutshell, what Napster adds to the 
“two FTP servers" scenario is integration with a search 
engine. (From a sociological point of view, Napster also 
adds ease of use, and a focus on a specific type of 
content.! Searches in Napster are preformed via a central 
server which indexes the music on each of the 
connected Napster clients. This allows for fast and 
efficient searching. But actual file transfers are 
conducted direcily between two client machines, 
without passing through any centralized server. This is 
key, because it allows the Napster system as a whole to 
effectively take advantage of Lite aggregate bandwidth 
and disk space of all of its users *—- there is no need for 
a huge disk farm to store the content, and an unlimited 
number of transfers between clients can happen 
simultaneously without impacting the performance of 
Lite system as a whole. The decentralized aspects are in 
a sense the most inspired strength of Napster, and they 
are really what has sparked interest in peer-to-peer 
technologies in themselves. The centralized search 
facilities are in a sense the greatest weakness, but more 
from a political or legal point of view than from a 
technological one, because they necessitate a single 
authority which can lx: targeted with legal action, and an 
essential linchpin which can lie “attacked" to shut down 
the entire system. Unsurprisingly, this has led to a trend 
in new p2p technologies to try to avoid any 
centralization at all, in order to provide both legal and 
technological robustness against attempts io shut down 
any systems developed. This backlash is a mixed 
blessing, because centralization in and of itself it nor 
always a flaw — some operations are appropriate to 
centralize, such as searching, and in the absence of 
worries about “social attacks" this is often the best 
approach. At the same time, a community obsessed with 
maximizing the “p" in p2p is producing some interesting 
systems which are pushing the limits of what would 
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have been thought to be possible in a purely distributed 
peer system, and is giving us greater insight into what 
can and cannot be done without centralization. Alter the 
legal controversy dies down I think that we will again 
be designing systems which are a sensible mix of p2p 
and traditional client-server, bin they will be better than 
they would have been without the war stories from 
today's p2p innovators. 

Gnutella 

Gnutella began at AOL with developers from 
Nullsoft, the company behind the popular Winamp MP3 
player for Windows* and it quickly became on open 
source projeci being developed outside ol the company 
It has been described as the open-source Napster. At the 
surface this is true, but Gnutella differs from Napster in 
several important ways. 

To begin with, Gnutella is actually a protocol, rather 
than an application, and there are several different 
applications for multiple platforms which speak the 
Gnutella protocol. Like Napster, Gnutella software 
allows users to perform searches anti transfer files, and 
the same software plays the rote of both client and 
server, both downloading and vending content. The key 
difference is that Gnutella is completely decentralized 

there is no central entity to service queries. When a 
Gnutella application starts up, it joins the Gnutella 
network by connecting to another "‘node 11 -— to any 
other machine running Gnutella software. In the 
beginning, users would find another node to connect to 
through word-of-mouth, or from web sites which posted 
lists of IP addresses of nodes, but today there are nodes 
called "host caches" which are set up to vend the 
locations of active nodes to new users joining the 
network (one point of slight, and optional, 
centralization in Gnutella), Once a node has connected 
to a handful of other nodes, it is part of the network, 
and equivalent to every other node, This has been 
described as a software-based network on top of the 
physical network, and it's in a constant state of llux as 
new nodes join and others drop out — as new 
connections form and old ones are severed, from one 
minute to the next. When a user want to search the 
network for a piece of content, his node sends his query 
to each of its “adjacent 1 ' nodes (the nodes to which it is 
connected), which in turn forward the query to the 
nodes that they know about, and so on. bach node can 
then respond to the query by sending its response buck 
along the network to the node which originated the 
query. In case you missed it, Gnutella queries happen 
via a broadcast across the network of users, rather than 
through a central server which indexes all of the 
content. More about this in a minute. As responses to a 
query trickle back u> a node, if any of them contain the 
URL of a file that the user want to download, he can 
download it directly from the machine which sent that 


response. This is the same strategy employed by 
Napster, in that the (potentially large) file transfers 
bypass the greater Gnutella network completely. 

In addition to the search strategy, Gnutella differs 
from Napster in the search content. A Gnutella query is 
free-form, and each node is independent and free to 
interpret a query however it likes. Napster treats queries 
as searches for MP3s t but a Gnutella query could he 
looking for music, some other type of file, or a different 
kind of information entirely. Most commonly, a node 
will treat a query as a request for a file, and will match 
the query against either file names or file content (the 
former would he appropriate for an MP3, and the latter 
for a news article), Bui to demonstrate the flexibility of 
this approach, Gnutella developers set up a small 
network with nodes which each handled queries in a 
different way — one interpreted them as requests for 
stock quotes, one matched them against news headlines, 
and another evaluated them as arithmetic expressions — 
and provided a web-based search interface to the 
network, this demonstrated the flexibility of the notion 
of a query along tile network, and also pointed out that 
private Gnutella networks could easily be set up to 
serve novel functions. (This Lype of private Gnutella 
network is trivial tt> set up — it’s just a set of nodes 
which don I happen 10 know about any nodes outside 
of a small set,) 

As mentioned above. Gnutella uses a broadcast-based 
approach to searching. This strategy is a key feature of 
Gnutella and its decentralization, and it's arguably its fatal 
flaw, it’s a Haw because queries take a significant amount 
of bandwidth across the network, and this poses a direct 
barrier to scalability. Gnutdla’s approach is actually quite 
strange, once you begin to analyze it, and it's difficult to 
decide whether its clever or pathological. Although 
logically a broadcast, queries are passed from node to node 
via direct TCP/IP connection, rather than via UDP 
broadcast. Also, despite being TCP-based, the queries are 
lossy — nodes will discard their responses if querying 
nodes are reacting too slowly. This saves things somewhat, 
as it prevents a few slow nodes from clogging the network. 
Also, queries have a time to live (TI L), just like IP packets 
— typically, Gnutella queries have ;t TTL ol 7. meaning that 
queries are only transmitted to nudes 7 hops away. On 
average, a query reaches about 10.000 other nodes. 

The Gnutella community is quick to point out that 
tliis “distributed query" approach models the way 
humans interact. Transferring knowledge in an ever- 
changing network of interactions. On the other hand, as 
nice as the analogy may sound, it might not be the best 
design strategy, and the comparison breaks down in the 
details. If you do I lie math, even w r ith ITLs and lossy 
responses, the performance of Gnutella networks will 
degrade and hit a bandwidth wall when the network 
grows above a certain number of nodes. Steps are being 
taken to address the “bandwidth issue", and more 
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sophisticated software is being developed to implement 
various strategies. Interestingly, this problem is no 
surprise to Gnutella developers — it was known at the 
very beginning, and is an inherent problem with 
broadcasts. Nevertheless, developers persisted in this 
approach, demonstrating an enthusiasm (or dementia) 
which has been attendant to p2p development, 
characterized as a willingness to go ahead and try things 
which seem “theoretically impossible but practically 
possible". This sounds like a rather irrational philosophy 
for a community of developers, but despite riiLs Gnutella 
lias actually performed better than the naysayers 
predicted, and has given us a better idea of what is 
possible with this type of approach. And although the 
Gnutella community is now forced to do some 
technological clean up, they arc able to address the real 
problems that have actually arisen, at a poinL where 
they know the strengths and weaknesses of their system 
better than they would have to start out with, and so are 
in a better position to solve them. 

Further Reading 

If you want to learn more about the ever-changing 
p2p landscape, and about Gnutella in particular, there are 
several great places to start. O'Reilly's Open P2P portal site 
cxmtatns original content as well as pointers to articles on 
other sites, and lias a Gnutella section which can help you 
keep up to speed as the tec hnology develops. O’Reilly 
also has a recently-published book, Peer-to-Peer: 
Harnessing the Pouter of Disruptive Technologies (ISBN: 0- 
596-001 10-X), with articles on specific p2p technologies as 
well as articles covering general topics which are relevant 
across applications. In particular, check out “Gnutella: 
Alive, Well, and Changing Fast" and "Gnutella and the 
Transient Web" here, and “The Gnutella paradox" on 
Sakm.com, Also, the Gnutella web site at wego.com is a 
portal for both Gnutella developers and users, and 
Gnutelliums maintains information on all of the Gnutella 
clients available for various platforms. If you are interested 
in developing p2p software* or just in figuring out how 
certain things are done, the source code to these clients 
(often licensed under the GPL) is a great resource. It's 
often included with die client distributions, or you can find 
much of it at Gnutella Dev. And finally, if you plan on 
doing any Gnutella development, you 11 need to know the 
details of the protocol, which you can find at Gnutelliums 
and at Cltp2. 

0penP2P.com 

<http://www.openp2p.com/> 

0penP2P.com; Gnutella 

<http://www.openp2p.com/topics/p2p/gnutella/> 

Gnutella; Alive, Well, and Changing Fast 

<http://www + openp2pxom/pub/a/p2p/2001 /G1 /25/trueloveOt 01 ,html> 


Gnutella and the Transient Web 

<http://www.openp2p.eom/pub/a/p2p/2001/03/22/truelove.htmi> 

The Gnutella paradox 

<http://www, salon, com/tech/feature/2000/09/29/gnutella_paradox/> 

Gnutella porta! page 

<http://gnutella.wego.com/> 

Gnutelliums 

<http://www.gnutetliums.com/> 

Gnutella Dev 

<http://www.gnutelladev.com/> 

The GnutellaNet protocol at MR0B 

<http://www t gnutelliums,com/linux unix/gnut/doc/gnutella 
prothtml> 

The Gnutella Protocol Specification vQ,4 

<http://d5S,dip2.com/Gnutel!aProtocol04,pdf> 

Lessons from Gnutella and Napster 

The genesis and growth of Gnutella and Napster 
have a lot to tell us about both the technological and 
the sociological aspects of new technologies. In 
particular, Napster is popular not because it is p2p, but 
because people really like music —- it's the content 
that's really important to the end user, not the means to 
gel there, and it jusl happened that in Napster’s case 
pip was the best way to deliver this. I also find it telling 
that Napster isn't web browser based, but Instead uses 
its own standalone client. This confounds die prevailing 
wisdom today dial everything needs to live in a browser 
or the public won't use it. In Napster's case, it really 
wasn't technologically feasible to work inside of a 
browser, and I 11 1 ink it would have been a disaster if 
they had tried. The important lesson here is that if the 
content is compelling enough, and the technology 
delivers it well, then users are perfectly happy 
downloading a new piece of software to use. They 
really don't need to use Netscape or IK for everything, 
and 1 hope that developers realize this as they are 
planning for the next generation of applications, 

In a way, Gnutella is a result of embracing the 
technology of Napster and inferring a set of ideals from 
it, rather than understanding whaL really has made it 
popular. On the other hand, there's really nothing wrong 
with that, and I don't think the Gnutella community 
would mind being accused of putting die cart before die 
horse. Nut everything has to be the basis for a business 
plan, after all. Enthusiasm for the idea of p2p and a 
willingness to experiment are improving the underlying 
technology, and showing us what is possible, and in 
some cases how simply things can be done. And in the 
end, people are having fun with it — both developers 
and users, The "let's just try it and see what happens" 
approach is working out pretty well in fact. So when a 
business plan does come along, they'll be ready, GS3 
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